Vanilla Forums: Community Forums Evolved

Internationalization & Localization

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.

Supporting Translation in Your Own Addons

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 T().

Translating Vanilla to Your Locale

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.

Where to Put Locale Files in Addons

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.

Application: applicationfolder/locale/en-CA/definitions.php
Plugin: pluginfolder/locale/en-CA.php
Theme: themefolder/locale/en-CA.php

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.

Using the Baseline Locale Addon

There is a Baseline Locale addon available in our addons repository that you can use to build your custom locale definitions. To Get Started:

download the Baseline Locale addon
Uncompress the archive, and rename the folder to a phrase with only alphanumeric characters (no spaces, dashes, etc). Example: "danish".
Open the definitions.php file, and update it with your information. Be sure to replace the 'LocaleKey' value (it is "Baseline" by default) with the same name you chose for the containing folder.
Open the captured.php and captured_admin.php files and replace the English definitions with the appropriate values for your language.

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.

Enabling a Locale Pack on Your Site

Once you have a locale pack you can enable it on your site using these steps:

Copy the locale pack to your /locales folder.
Go to you dashboard under locales and enable the locale pack.
Make sure your locale is selected as the default locale at the top.

The Locale Developer Plugin

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.