﻿This is just a little file that explains
 __ __   ___   __    __    ______   ___  
|  |  | /   \ |  |__|  |  |      | /   \ 
|  |  ||     ||  |  |  |  |      ||     |
|  _  ||  O  ||  |  |  |  |_|  |_||  O  |
|  |  ||     ||  `  '  |    |  |  |     |
|  |  ||     | \      /     |  |  |     |
|__|__| \___/   \_/\_/      |__|   \___/

USE STRUCTORIZER LOCALES
========================
Authors:     Bob Fisch, Kay Gürtzig
Last Update: 2018-07-02

1) All language files ...
    - reside inside the package lu.fisch.structorizer.locales
    - must be registered in the list Locales.LOCALES_LIST
      (Actually the buttons in the Translator are not yet being
       generated automatically, neither is the menu in Structorizer
       itself.)

2) The actual API supports 4 components. If you add something
   new to this project, you just need to make your class extend
   the corresponding Lang-class.

    JFrame      -->     LangFrame
    JDialog     -->     LangDialog
    JPanel      -->     LangPanel
    JMenuBar    -->     LangMenuBar

   Important note: The LangDialog is being repacked by default
   after a locale is being loaded. If you do not want this
   behavior, call setPacking(false) somewhere in your constructor.

3) The syntax of the language files can be described like this.

    - The file is composed of a "header" and a "body". The header
      must always precede the body. Both are separated by a line
      containing this string: >>>

    - The body contains sections and each section may contain
      sub-sections. The body *MUST* start with a section!
      A section is indicated by the prefix: ----->  
      A sub-section is prefixed by:         -----[
      In the translator component, each section is presented in
      a new tab whereas a sub-section is drawn as a visual separator.

    - A parsed line looks like this: key=value

        "value" can be any text you want to put into the target specified by the key
        
        	* Yet there are some kind of place holders in the texts, which are
        	  used for certain replacements (see section 4 below). 
        
        "key" is a dot-separated string:
            
            * The first part is the name of the class of the object
              this line wants to modify
            
            * The second part might be "title", which will then modify
              the object's title, or the name of the field that is to
              be modified.
              (If the field happens to be an array or another indexed collection
              then an additional integer part will have to be inserted here.)

            * The third part is the attribute to be modified. This can
              be for now:

                > text  
                > tooltip
                > border
                > mnemonic

                > tab
                > header
                > item

              The last three entries may be followed by a forth part
              which has to be an integer and represents the index of
              the element to modify.

            * Finally, the key may have a condition section. This one is indicated
              (and enclosed) by square brackets. It can contain multiple conditions,
              which will be combined using an AND operator.

              The conditions use the syntax: field:value
                                         or: method():value
                                       
              The value of the line will only be affected to the key if all
              field:value and method():value pairs match. Comparison is
              string-based!

   Examples
   --------

    >>> The title of a dialog:      
        ExportOptionDialog.title=Export options ...

    >>> The tooltip of a button:    
        PrintPreview.btnOrientation.tooltip=Turn the page by 90°.

    >>> The name of a tab:          
        About.pnlTabbed.tab.2=License

    >>> The name of a checkbox held in an array:
        AnalyserPreferences.checkboxes.1.text=Comprobar modificación de la variable del bucle.
        
    >>> The common tooltip of all text fields held in an array (asterisk means all indices):
        ExportOptionDialog.includeLists.*.tooltip=Fill in a comma-separated list of ... 
        
    >>> A common, but modified text of all labels held in an array (asterisk means all indices),
            but with inserted index (note that "[#]" will be replaced with the actual array index):
        lblColors.*.text=Color [#] 
        
    >>> Conditional text of a label:
        InputBox.lblText.text[elementType:Alternative]=Eingabe der Bedingung an dieser Stelle.

    >>> Conditional (combined) title of a dialog
        InputBox.title[elementType:Repeat,getInsertionType():insert]=Neue REPEAT-Schleife hinzufügen...
                
4) Place holders in the text values:

       The texts may contain three kinds of place holders that should be preserved
       at appropriate positions in the translations:
       - "%", "%1", "%2" etc. for message-specific replacements;
       - "[#]" to be substituted with the current array index for array targets
         (particularly those with "*" as index in the key);
       - "@a", "@b", ... "@p", or "@{Instruction}", @{For}" etc. for localized
         element names. The localized element names are defined in (and retrieved
         from) section / tab "Elements" with the following convention, where the
         respective short and long place holders are equivalent (the short one is
         more performant, the long one more readable):
   
         short long                    referenced key sequence
         @a  = @{Instruction}      ->  ElementNames.localizedNames.0.text
         @b  = @{Alternative}      ->  ElementNames.localizedNames.1.text
         @c  = @{Case}             ->  ElementNames.localizedNames.2.text
         @d  = @{For}              ->  ElementNames.localizedNames.3.text
         @e  = @{For.COUNTER}      ->  ElementNames.localizedNames.4.text
         @f  = @{For.TRAVERSAL}    ->  ElementNames.localizedNames.5.text
         @g  = @{While}            ->  ElementNames.localizedNames.6.text
         @h  = @{Repeat}           ->  ElementNames.localizedNames.7.text
         @i  = @{Forever}          ->  ElementNames.localizedNames.8.text
         @j  = @{Call}             ->  ElementNames.localizedNames.9.text
         @k  = @{Jump}             ->  ElementNames.localizedNames.10.text
         @l  = @{Parallel}         ->  ElementNames.localizedNames.11.text
         @m  = @{Root}             ->  ElementNames.localizedNames.12.text
         @n  = @{Root.DT_MAIN}     ->  ElementNames.localizedNames.13.text
         @o  = @{Root.DT_SUB}      ->  ElementNames.localizedNames.14.text
         @p  = @{Root.DT_INCL}     ->  ElementNames.localizedNames.15.text
