Table Of Contents

1. Using languages
2. Translation Volunteers
3. Documentation Translation
4. Album messages
5. 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�ais"
instead of "French"

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

1) HTML characters such as [é]] (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!