MarginalHacks album - Language Support - Documentation

| A l b u m E i g h t - - L a n g u a g e S u p p o r t

### Home
### Themes/Examples
### Languages
### Plugins
### License
### Download
### Documentation English Deutsch Espa帽ol Fran莽ais Nederlands 袪褍褋褋泻懈泄 Italiano magyar
### Mailing List
### CHANGELOG
### Praises
### Contact
| Table Of Contents Using languages Translation Volunteers Documentation Translation Album messages Why am I still seeing English?
    1:   Using languages
    (Requires album v4.0 or higher)

    Album comes prepackaged with language files (we're in need of translation
    help, see below!).  The language files will alter most of album's output
    messages, as well as any HTML output that isn't generated by the theme.

    Altering any text in a theme to match your language is as simple as editing
    the Theme files - there is an example of this with the "simple-Czech" theme.

    To use a language, add the "lang" option to your main album.conf, or else
    specify it the first time you generate an album (it will be saved with that
    album afterwards).

    Languages can be cleared like any code/array option with:

    % album -clear_lang ...

    You can specify multiple languages, which can matter if a language is
    incomplete, but you'd like to default to another language than english.
    So, for example, if you wanted Dutch as the primary language, with the
    backup being Swedish Chef, you could do:

    % album -lang swedish_chef -lang nl ...

    If you specify a sublanguage (such as es-bo for Spanish, Bolivia), then
    album will attempt 'es' first as a backup.

    Note that because of a known bug, you should specify all the desired
    languages at the same time instead of over multiple invocations of album.

    To see what languages are available:

    % album -list_langs

    Sadly, most of the (real) languages are barely complete, but this
    is a chance for people to help out by becoming a..

    2:   Translation Volunteers

    The album project is in need of volunteers to do translations,
    specifically of:

    1) The Mini How-To.  Please translate from the source.
    2) album messages, as explained below.

    If you are willing to do the translation of either one or both
    of these items, please contact me!

    If you're feeling particularly ambitious, feel free to translate any
    of the other Documentation sources as well, just let me know!

    3:   Documentation Translation

    The most important document to translate is the "Mini How-To".
    Please translate from the text source.

    Also be sure to let me know how you want to be credited,
    by your name, name and email, or name and website.

    And please include the proper spelling and capitalization of the
    name of your language in your language.  For example, "fran鏰is"
    instead of "French"

    I am open to suggestions for what charset to use.  Current options are:

    1) HTML characters such as [&eacute;]] (though they only work in browsers)
    2) Unicode (UTF-8) such as [茅] (only in browsers and some terminals)
    3) ASCII code, where possible, such as [閉 (works in text editors, though
       not currently in this page because it's set to unicode)
    4) Language specific iso such as iso-8859-8-I for Hebrew.

    Currently Unicode (utf-8) seems best for languages that aren't covered
    by iso-8859-1, because it covers all languages and helps us deal with
    incomplete translations (which would otherwise require multiple charsets,
    which is a disaster).  Any iso code that is a subset of utf-8 can be used.

    If the main terminal software for a given language is in an iso charset
    instead of utf, then that could be a good exception to use non-utf.

    4:   Album messages

    album handles all text messages using it's own language support
    system, similar to the system used by the perl module Locale::Maketext.
    (More info on the inspiration for this is in TPJ13)

    An error message, for example, may look like this:

      No themes found in [[some directory]].

    With a specific example being:

      No themes found in /www/var/themes.

    In Dutch, this would be:

      Geen thema gevonden in /www/var/themes.

    The "variable" in this case is "/www/var/themes" and it obviously
    isn't translated.  In album, the actual error message looks like:

      'No themes found in [_1].'
      # Args:  [_1] = $dir

    The translation (in Dutch) looks like:

      'No themes found in [_1].' => 'Geen thema gevonden in [_1].'

    After translating, album will replace [_1] with the directory.

    Sometimes we'll have multiple variables, and they may change places:

    Some example errors:

      Need to specify -medium with -just_medium option.
      Need to specify -theme_url with -theme option.

    In Dutch, the first would be:

      Met de optie -just_medium moet -medium opgegeven worden.

    The actual error with it's Dutch translation is:

      'Need to specify [_1] with [_2] option'
      => 'Met de optie [_2] moet [_1] opgegeven worden'
      # Args: [_1]='-medium'  [_2]='-just_medium'

    Note that the variables have changed places.

    There is also a special operator for quantities, for example,
    we may wish to translate:

      'I have 42 images'

    Where the number 42 may change.  In English, it is adequate to say:

      0 images, 1 image, 2 images, 3 images...

    Whereas in Dutch we would have:

      0 afbeeldingen, 1 afbeelding, 2 afbeeldingen, 3 afbeeldingen..

    But other languages (such as many slavic languages) may have special
    rules as to whether "image" should be pluralized based on whether the
    quantity is mod 2, 3 or 4, and so on!  The simplest case is covered
    by the [quant] operator:

      [quant,_1,image]

    This is similar to "[_1] image" except that "image" will be pluralized
    if [_1] is 0 or greater than 1:

      0 images, 1 image, 2 images, 3 images...

    Pluralization is simply adding an 's' - if this isn't adequate, we can
    specify the plural form:

      [quant,_1,afbeelding,afbeeldingen]

    Which gives us the Dutch count above.

    And if we need a special form for 0, we can specify that:

      [quant,_1,directory,directories,no directories]

    Which would create:

      no directories, 1 directory, 2 directories, ...

    There is also a shorthand for [quant] using '*', so these are the same:

      [quant,_1,image]
      [*,_1,image]

    So now an example translation for a number of images:

      '[*,_1,image]'
      => '[*,_1,afbeelding,afbeeldingen]',

    If you have something more complicated then you can use perl code, I
    can help you write this if you let me know how the translation should work:

      '[*,_1,image]'
      => \&russian_quantity;	# This is a sub defined elsewhere..

    Since the translation strings are (generally) placed in single-quotes (')
    and due to the special [bracket] codes, we need to quote these correctly.

    Single-quotes in the string need to be preceded by a slash (\):

      'I can\'t find any images'

    And square brackets are quoted using (~):

      'Problem with option ~[-medium~]'

    Which unfortunately can get ugly if the thing inside the square brackets
    is a variable:

      'Problem with option ~[[_1]~]'

    Just be careful and make sure all brackets are closed appropriately.

    Furthermore, in almost all cases, the translation should have the
    same variables as the original:

      'Need to specify [_1] with [_2] option'
      => 'Met de optie [_2] moet'              # <- Where did [_1] go?!?

    Fortunately, most of the work is done for you.  Language files are
    saved in the -data_path (or -lang_path) where album keeps it's data.
    They are essentially perl code, and they can be auto-generated by album:

    % album -make_lang sw

    Will create a new, empty language file called 'sw' (Swedish).  Go ahead
    and edit that file, adding translations as you can.  It's okay to leave
    translations blank, they just won't get used.  Some of the more important
    translations (such as the ones that go into HTML pages) are at the top
    and should probably be done first.

    You will need to pick a charset, this is tricky, as it should be based
    on what charsets you think people will be likely to have available
    in their terminal as well as in their browser.

    If you want to build a new language file, using translations from
    a previous file (for example, to update a language with whatever
    new messages have been added to album), you should load the language first:

    % album -lang sw -make_lang sw

    Any translations in the current Swedish language file will be copied
    over to the new file (though comments and other code will not be copied!)

    For the really long lines of text, don't worry about adding any newline
    characters (\n) except where they exist in the original.  album will
    do word wrap appropriately for the longer sections of text.

    Please contact me when you are starting translation work so I can
    be sure that we don't have two translators working on the same parts,
    and be sure to send me updates of language files as the progress, even
    incomplete language files are useful!

    If you have any questions about how to read the syntax of the language
    file, please let me know.

    5:   Why am I still seeing English?

    After choosing another language, you can still sometimes see English:

    1) Option names are still in English.  (-geometry is still -geometry)
    2) The usage strings are not currently translated.
    3) Plugin output is unlikely to be translated.
    4) Language files aren't always complete, and will only translate what they know.
    5) album may have new output that the language file doesn't know about yet.
    6) Most themes are in English.

    Fortunately the last one is the easiest to change, just edit the theme
    and replace the HTML text portions with whatever language you like, or
    create new graphics in a different language for icons with English.
    If you create a new theme, I'd love to hear about it!
Created by make_faq from Marginal Hacks

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |