Gallery3:Developer Handbook:Internationalization

Internationalization

All user visible strings in Gallery 3 are internationalized. Internationalization is the process of preparing a string so that a volunteer can translate it into their native language. Internationalized and localized strings are stored in the database, not on the filesystem.

There are two global functions used to internationalize all strings, one for singular strings and one for strings containing plural forms. Additional Localization info.

Simple internationalization

If you have a simple string that has no plural forms in it and no variables in it, then localization is very simple using the t() function. Simply pass your string in as an argument, eg:

In a controller, helper or library:

 $hello_world = t("Hello, world");

In a view:

 <?= t("Hello, world") ?>

Internationalization with variables

If you need to craft a string with variable values in it, you can use the optional array argument to the t() function call and embed placeholders in your internationalized string. Placeholders are words prefixed by a percent (%) sign. The placeholder word matches a key in the optional array argument. You can have as many placeholders as you want. For example:

In a view:

 <?= t("Hello, %name", array("name" => $user->name) ?>

In a controller, helper or library:

 $info = t("%name created %title",
         array("name" => $user->name,
                  "title" => $item->title));

Internationalization with plural forms

Each locale has its own rules for plural forms and the rules get quite complicated, but to properly internationalize a string with plural forms in it, you simply have to separate the singular form of the string from the plural form and use the t2() call with the special %count variable in your internationalized string. In the singular form, you do not need to use the variable.

In a view

 <?= t2("I have one apple", "I have %count apples", $count) ?>

You're also free to use plural forms with variables, for example:

In a controller, helper or library

 $info = t2("Hey %name, you have %count apples",
            $count,
            array("name" => $user->name));

Any internationalized string you add to your module will be detected by Gallery 3 when the administrator browses to the Admin > Languages page and updates their translations. Localizers who install your module can localize your strings into their native language and upload those localizations to the Gallery website which will in turn make those localizations available to all users of the module.

Notes about internationalization:

• The code scanner that Gallery 3 uses to find your internationalized strings does not recognize strings that are concatenated. Each internationalized string must be a single long string without linebreaks or concatenation.
• Internationalized strings should not have PHP variables in them. For example, do not use t("Using $variables is bad"). These strings will not be localized properly.
• HTML markup is ok in localized strings, but it's best to keep it simple.
• Use variables for any part of the string that might reasonably change in the future, like URLs. For example:

 t("See <a href=\"%url\">the documentation</a>",
   array("url" => "http://docs.com"))

• Avoid multiple plural forms in a single string, they cannot easily be localized:

 t("%count apples and %num oranges",
   $count,
   array("num" => $num))

• In this example, you really need four forms to cover all the cases where apples can be singular/plural and oranges can be singular/plural. It's best to find a way to rewrite the text to keep it separate.
• Longer strings are eaiser to localize than short ones, and localizers often times cannot figure out how to localize multiple short strings that are concatenated. Instead of doing this:

  <?= t("I like") ?>
  <? if ($bacon): ?>
    <?= t("to eat bacon") ?>
  <? else: ?>
    <?= t("to fry eggs") ?>
  <? endif ?>

prefer to use:

  <? if ($bacon): ?>
    <?= t("I like to eat bacon") ?>
  <? else: ?>
    <?= t("I like to fry eggs") ?>
  <? endif ?>