USING MAGENTO TRANSLATION TOOLS

Transcription

1 Magento Translation Tools 1 USING MAGENTO TRANSLATION TOOLS Magento translation tools make the implementation of multi-language Magento stores significantly easier. They allow you to fetch all translatable strings from Magento and your customized templates, create CSV files from them, and the biggest time saver to translate the files automatically using one of the available community translations. They also make it easier to find which strings require translation due to the fact that they did not exist in the base translation. It is even possible to use translations from other Magento versions as a base if a translation matching your project version is not available. Installation Unpack the archive into the tools directory in the root Magento directory. This directory should not be part of the live site. Make sure to install it only on the development site and do not propagate to the live site. Use case 1: Generating files for translation based on existing community translations Configuration Before the tools can be used, it is required to prepare a configuration file (config.inc.php) that lists all directories which contain translatable files, assign files to specific translation modules, and provide mapping between helper names and module names. Mapping between helper names is required to put strings extracted from calls like: Mage::helper('catalogrule')-> ("Name: %s", $this->getname()) To the Mage_CatalogRule module (and as a result in the Mage_CatalogRule.csv translation file) The default configuration includes all Magento modules and default templates. To translate your project, you need to add specifications for all your custom modules that include any translatable strings, and all your custom templates.

2 Magento Translation Tools 2 There is also a section referring to the 'translate' module. All template files that are not related to any specific module should be assigned there. Usage The translation process consists of the following steps: 1) Extract all translatable strings from the Magento code into one file A 2) Combine community translations/previous translations from many CSV files into another file B 3) Go through the A file translating all matching strings using the B file as the reference 4) Split the partially translated file into many CSV files that Magento can use 5) If the files were not fully translated, they should be translated now (can be done before or after splitting) Each of the steps is automated using the provided tools. Next we will explain each step and provide instructions on using the tools. 1) Extract translatable strings When your configuration file is ready, it's time to extract translatable strings from PHP code into CSV files. php -f generate.php -- --output all.csv This will create file all.csv containing all extracted strings, the modules to which they belong, the files from which they were extracted, etc. As the file is created in the Magento root directory, move it to the tools/translate directory. 2) Combine community translations The first step is to install community translations for required languages using Magento Connect. The installed files will be put in directories like app/locale/fr_fr and other similar directiories. When this is ready, it's time to put all translations for the given language into one big file. We will use the French locale as an example.

3 Magento Translation Tools 3 php -f combine.php -- --output fr_fr_org.csv --locale fr_fr This will create the file fr_fr_org.csv using files from the app/locale/fr_fr directory. 3) Merge translations The next step is to use the available translations from the previous step to pre-translate your Magento project. php -f Merge.php -- --of all.csv --tf fr_fr_org.csv --mf fr_fr.csv --diff where fr_fr_org.csv is the file created in step 2 and fr_fr.csv is the merged result. The diff option is optional and means the resulting file will have another column with the value true when the string was translated or false if the string was not translated (or is the same as the original). This offers a great help to translators as they can concentrate fully on entries that show false. After merging, the tool shows statistics regarding how much information it was able to reuse. 4) Split translations The final step involving translation tools is to split the pre-translated file created in step 3 into a set of files readable by Magento. Before this can be done, clear the language directories app/locale/ from the CSV files. When this is complete, run: php -f split.php -- --input fr_fr.csv --locale fr_fr This will put into app/locale/fr_fr the set of CSV files that Magento can actually use for translations. You can enable them right away by configuring the store for the given locale and clearing the translation cache. If during merging (step 3) you have used the option diff, the final files will also have the column showing if the given string was translated or not. This column is skipped by Magento and can be very helpful for the translator.

4 Magento Translation Tools 4 Tip: You can also split the en_us locale (from all.csv) so that it will also have the latest files. This allows you to modify the default Magento English texts easily. There is also a translate.csv file created in app/local/fr_fr. It should be copied to app/design/frontend /.../locale/... for your template. 5) Translating files The files can be translated either before or after splitting. After translation, they should be reviewed and copied back to the respective directories. After clearing the translation cache they will be activated. To avoid confusion and double work, translators have to make sure they are editing the files in UTF-8 mode. One simple way to work with the files is to use the OpenOfffice Calc spreadsheet application as it properly opens UTF-8 encoded CSV files. Open the file from the menu choosing UTF-8 as the encoding. When saving, make sure the following options are used: encoding: UTF-8 delimiter:, (comma) enclosing: " (double quote) Tip: Translating files in a spreadsheet often leads to language inconsistency. Translators often use CAT (Computer Aided Translation) tools to help reuse previous translations and keep consistent naming. Magento CSV translation files can be used in an Open Source CAT tool called OmegaT - more details are available at the following wiki page: ation_memory_software.

5 Magento Translation Tools 5 Use case 2: Generating translation files for your own modules Configuration Before the tools can be used, it is required to prepare a configuration file (config.inc.php) that lists all directories that contain translatable files, assigns files to specific translation modules, and provides mapping between helper names and module names. Mapping between helper names is required to put strings extracted from calls like Mage::helper('catalogrule')-> ("Name: %s", $this->getname()) To the Mage_CatalogRule module (and as a result in the Mage_CatalogRule.csv translation file) The default configuration includes all Magento modules and default templates. To translate your module, you need to add specifications for all your custom modules that include any translatable strings, and all your custom templates - or you can replace the existing configuration with the configuration related only to your module. There is also a section referring to the 'translate' module. All template files that are not related to any specific module should be assigned to there. A sample configuration for a payment module TestPay that has its own layout files: $CONFIG['translates'] = array( ); ), 'Testproject_Testpay' => array( 'app/code/local/testproject/testpay/', 'app/design/frontend/testproject/default/layout/testpay.xml', $CONFIG['helpers'] = array( 'testpay' => 'Testproject_Testpay', );

6 Magento Translation Tools 6 Usage 1) Extract translatable strings When your configuration file is ready, it's time to extract the translatable strings from the PHP code into the CSV files. php -f generate.php -- --output testproject.csv This will create the file testproject.csv containing all the extracted strings, the module to which they belong, the file from which they were extracted, etc. As the file is created in the Magento root directory, move it to the tools/translate directory. 2) Split translations The final step involving translation tools is to split the file created in step 1 into one or a set of files readable by Magento. php -f split.php -- --input testproject.csv --locale en_us This will put into app/locale/en_us a set of CSV files (one for each module declared) that Magento can actually use for translations. You can enable them right away by configuring the store for the given locale and clearing the translation cache. Summary Magento makes it possible to create multi-language international stores with ease due to its flexible translation architecture, full support for UTF-8 encoding, and ability to change text both on the file level (translation files) and on the database level (inline translations that override file translations). Thanks to the community, Magento has been translated into many languages, fully or partially. The tools described above make it easy to reuse community translations in your own projects and provide base translation files for your own modules and extensions. Happy translating!