silverstripe-framework/docs/en/misc/translation-process.md
2012-11-21 16:15:48 +01:00

4.5 KiB

Translation Process

This page covers a few advanced topics related to SilverStripe's translation system.

To find out about how to assist with translating SilverStripe, see the Contributing Translations page.

Set up your own module for localization

Collecting translatable text

As a first step, you can automatically collect all translatable text in your module through the i18nTextCollector task. See i18n for more details.

Import master files

If you don't have an account on getlocalization.com yet, create one. Choose the free option for public repositories.

On the "Files" tab, you can choose "Import from SCM", and connect getlocalization to your github account. Alternatively, upload the en.yml file in the "Ruby on Rails" format.

If you don't have existing translations, your project is ready to go - simply point translators to the URL, have them sign up, and they can create languages and translations as required.

Import existing translations

In case you have existing translations in YML format, there's a "New language file" option in the "Files" tab.

IMPORTANT: Composite locales need to be uploaded with a dash separator, which is different from the core format (underscores). For example, to upload a file called en_GB.yml, change the first line in this file from "en_GB" to "en-GB".

Export existing translations

As a project maintainer, you have the permission can simply download the whole language pack as a ZIP archive and add it to your project. But for composite locales (e.g. "en-GB"), you have to change the keys in the first line of the file.

We encourage you to use the SilverStripe build tools for this instead, as they run some additional sanity checks. They require the "phing" tool. Create a 'translation-staging' branch in your module before starting, and merge it back manually to your 'master' as required.

Install the buildtools project.

# Add your own getlocalization config to 'build.properties'
cp buildtools/build.properties.default build.properties
phing -Dmodule=<yourmodule> -propertyfile build.properties translations-sync

Merge back existing translations

Since the latest translations are downloaded into a "translations-staging" branch, you need to get them back into your main project repository. This depends on your release strategy: For simpler modules, just merge back to master:

git checkout master
git merge translations-staging

In case you are maintaining release branches, its a bit more complicated: The "translations-staging" branch is (correctly) based off master, but you don't want to merge all other master changes into your release branch. Use the following task to copy & commit the specific files instead:

phing -Dmodule=<yourmodule> translations-mergeback

Converting your language files from 2.4 PHP format

The conversion from PHP format to YML is taken care of by a module called i18n_yml_converter.

Download Translations from GetLocalization.com

We are managing our translations through a tool called getlocalization.com. Most modules are managed under the "silverstripe" user there, see list of translatable modules.

Translations are exported from there into YML files, generated every hour, and committed to a special "translation-staging" branch on github. You can download individual files by opening them on github.com (inside the lang/ folder), and using the "Raw" view. Place those files in the appropriate directories on a local silverstripe installation.

Related

  • i18n: Developer-level documentation of Silverstripe's i18n capabilities
  • contributing/translation: Information for translators looking to contribute translations of the SilverStripe UI.
  • translatable: DataObject-interface powering the website-content translations
  • "Translatable ModelAdmin" module: An extension which allows translations of DataObjects inside ModelAdmin