In iTop and iTop modules, a language is identified by two things:

• The ISO 639-1 language code. Example: pt for Portuguese.
• The ISO country code. Example: br for Brazil.

Localization relies on dictionary files, which names are prefixed with the language code in lowercase, like : pt_br.dictionary.itop.core.php. Those files are part of the datamodel, so a compilation is needed after each modification (run the setup again or use the toolkit).

In iTop, the embedded dictionnaries are located in :

• <itop-root>/dictionaries/
• <itop-root>/datamodels/2.x/<module>/

In modules, thoses files are located in the module's root directory.

A dictionary is in fact a PHP file. It must be encoded in the utf-8 character set (this is a MUST). We recommend that the PHP closing tag be omitted as in the example given below.

<?php
/**
 * Localized data
 *
 * @copyright   Copyright (C) 2015 John Foo Ltd
 * @author      John Foo (john@foo.com)
 * @license     http://opensource.org/licenses/AGPL-3.0
 */

Dict::Add('PT BR', 'Brazilian', 'Portuguese', array(
	'Menu:ChangeManagement' => 'Gerenciamento Mudanças',
	'Menu:Change:Overview' => 'Visão geral',
	'Menu:NewChange' => 'New Change~~',
));

Notes:

• The first parameter of the function call is the language code in uppercase.
• The second parameter of the function call is the language name in english.
• The third parameter of the function call is the language name in the target language.
• The line Dict::Add must be the same amongst all the dictionnary files for the same language (yes, there are redundant information here).
• Notice the ~~ at the end of some strings. This suffix is not displayed to the end-user. It is added by Combodo when releasing a new version, revealing which new strings requires a translation.

• keep consistency : re-use already translated terms (form example “manager” is a word used in many keys)
• you can keep english terms if they are more understandable in the context
• try not to use formulations that are too familiar : iTop is a product used both by companies and its clients
• use camel case for class names
• there are standards for datamodel items : Class:<classname>, Class:<classname>/Attribute:<fieldname>. For example : Class:Ticket, Class:Ticket/Attribute:ref, Class:UserRequest/Attribute:status/Value:new
• if you want to translate a field label, do it for the class where the field is defined, and not in child classes. Example : ok for Class:Ticket/Attribute:ref but not Class:Change/Attribute:ref. If you need the later, then just add it to your iTop instance using a customization module.
• Try not to mention classes in action labels for generic users. This can be done for admin users though. If using a class label, capitalize it : eg Notification instead of notitication.

A new entry should be named after its domain and purpose, starting with the less specific information.

The most commonly used separator is ':' but '/' and '-' could also be found.

'Core:BulkExport:TextFormat' => 'Text fields containing some HTML markup',
'UI:CSVImport:TextQualifierCharacter' => 'Text qualifier character',
'DayOfWeek-Sunday-Min' => 'Su',

Use suffixes to define variations of the same label :

• '+' means a short description (to be shown in a tooltip most of the time)
• '?' means help / explanations (could fit on several lines)

'Core:SynchroAtt:update' => 'Update ?',
'Core:SynchroAtt:update+' => 'Used to update the object',
 
'UI:CSVImport:AdvancedMode' => 'Advanced mode',
'UI:CSVImport:AdvancedMode+' => 
  'In advanced mode the "id" (primary key) of the objects can be used to update and rename objects.'
  .'However the column "id" (if present) can only be used as a search criteria'
  .' and can not be combined with any other search criteria.',

When a naming convention is established, then the identifiers should be specified as <name>:<value>, like in the following example:

'Class:Event/Attribute:date' => 'Date',
'Class:Event/Attribute:date+' => 'date and time at which the changes have been recorded',

Note that, in this case, the separator should be '/'.

You'll have to create a fork from iTop main repository or the corresponding module repository, then do your modifications and propose them using a pull request : see the CONTRIBUTING.md file in the repo you're modifying for details.

A detailed procedure on pull request model is available in the GitHub help pages : Creating a pull request from a fork.

To add translations to an existing language : look for (grep) the ~~ and translate them in place.

find -name "de*dict*.php" | grep -v "env-" | xargs grep "~~"

To add translations for a new language : find out your language code and country code. Copy the english files (either dictionary.*.php or en.dict.*.php) into their respective directory, with the relevant prefix (like in pt_br.dict…). Translate them.

The pull request will then be analyzed by Combodo maintainers, and eventually merged into the original repository.