Like Vanilla 1, Vanilla 2 is built to handle multiple languages. Unlike Vanilla 1, there is no default translation file for Vanilla 2. Instead of using translation codes in the core application, the actual English words & phrases were used in most places. Sometimes when there is an especially long phrase then a shorter one is used as a code with the longer phrase.
The heart of Vanilla's localization support is the
T() function. If you want to make sure that other people can localize your addons then you need to wrap all of your text in a call to the
T() function like this:
echo T('Hello World!');
When you do this then other people can translate the phrase in a locale pack. The
T() function can take an optional argument when you have a longer phrase:
echo T('Changes saved.', 'Your changes were successfully saved. All other users will see your changes immediately.');
In this case a translator would key in on the
'Changes saved.' rather than the long sentence. You don't want to change the phrase that a translator changes in your code or else all translations will break. If you have a long sentence structure then you can ensure that you can update it without breaking translations by using the two argument version of
Translations in Vanilla are put in addons called locales. Each locale should be put in its own folder in the
/locales folder of Vanilla. Each locale must contain a file called definitions.php with an info array in it. The info array goes at the top of this file. It has the following format:
$LocaleInfo['LocaleKey'] = array( // The locale key must match the folder the locale is in. 'Locale' => 'en-CA', // The code of the locale 'Name' => 'The name of the locale.', 'Description' => 'Locale description goes here.', // Be as descriptive as possible. 'Version' => '1.0', // A version number compatible with php's version_compare(). 'Author' => 'Your name here.', 'AuthorEmail' => 'Your email here', // optional 'AuthorUrl' => 'Your url here' // optional );
Please do not use a locale code like 'en-CA' for your locale. Different people may make a locale pack with the same locale as you and both must be able to co-exist on the addons site and even in an application. Translations go after the info array and have the following format:
$Definition['Translation from T()'] = 'Translation goes here.'; $Definition['Hello World!'] = 'Bonjour tout le monde'; $Definition['Changes saved.'] = 'Vos modifications ont été enregistrées avec succès';
You can also split up your translations into different files and name them whatever you want, as long as they go in the same folder as your locale.
Say you've created a plugin and you've used the T() function as described above and now you want to create some locale files for it so that you can support other languages with your download. Depending on the type of addon the locale file goes in a different spot. For the examples below, let's say I'm adding locale files for en-CA.
In each of these cases you would put your translations as
$Definition['Code'] = 'Translation'; as described above.
Clear the .ini files in your /cache folder after adding a new translation file.
There is a Baseline Locale addon available in our addons repository that you can use to build your custom locale definitions. To Get Started:
We strongly recommend that you contribute your custom locales to the project by uploading them to our addons site! Once you've completed this process, you can use the following instructions to enable it on your site. Note: VanillaForums.com customers can email support at vanillaforums dot com with their custom locales to have us enable them for you.
Once you have a locale pack you can enable it on your site using these steps:
Figuring out exactly what you need to translate can be a little confusing since translations are all buried in various parts of the application. In order to help out, we've developed a plugin which can be found here. The plugin can collect all of the phrases in an application to a dummy locale which you can then fill in with your own translations. It can also collect the changes between two locales so you can figure out what you have left to translate.
|Edited July 2011 by Lincoln|