Translation guidelines

Below are some guidelines on how to work with translations when setting up new components in the scope of GeoNetwork.

Transifex

We use transifex for our translations. Any component should at least load the core translations with the most common terms. On top of that a component may load search, editor or admin. Finally components can add a targeted translation file for their component only. Targeted translations exist for example for schema-plugins.

Introducing new translation keys

Decision to add a new key or use an existing one is a careful process. We try and maintain a balance between being specific enough and not overloading translators with many similar translations. A key should be specific enough so a developer can identify to what component it refers. Consider that transifex does not display keys, but only the translated value in the default language (english).

For future versions of the software (4+) we are leaving the aspect behind that keys should be human readable (the software will fall back to the english translation, not the key itself).

Translation files are using the transifex json format and do not include any logics which may impact the functionality of the application. Unfortunately this is not the case for a substantial part of the current codebase, but should be considered for any upcoming developments

We recommend not to use html tags inside translation values. Use of parameters is allowed, e.g. 'We found {{num}} result(s)'.

Updating translation keys

Updating keys should be minimized at all times

Procedure to update a key is:

• duplicate the key for upcoming minor versions (4.1, 4.2)
• remove the duplicated key in next major release (3.0, 4.0, 5.0)

Other considerations:

• Consider that a new key needs to be translated again (but transifex will suggest similar translated values).
• Consider that Transifex does not support branches, patch releases should be able to benefit from upcoming minor releases.
• Before removal, the code needs to be scanned on any occurrences of that key.

Capitals and punctuation

Translation values should include Capitals and Punctuation. Because these aspects may vary over languages (LTR/RTL).

• Do not use CSS to Capitalize first letter of a translated string
• Do not add punctuation in code, eg {{'title'|translate}}:

Language codes

Some of the standards used within GeoNetwork heavily depend on 3-letter ISO language codes, in Transifex and on the web the 2 and 5 letter codes are more common maintained by IANA, W3C. For GeoNetwork we maintain the following conventions:

• A mapping between 3 letter and 2-5 letter code should be available
• We prefer to use the 2 letter code, unless introduction of the sub language is requested and maintained by a substantial community.

Working to a single language configuration and uniform language assignment

New components should adopt a central language configuration. A component can however add the possibility to override that configuration by the end user. Current language is determined in this order

• A central configuration indicates which languages are available, which is the default one and if it should override the request language
• An explicit ?l=fr can be added to any request to override the language
• A user can set a language override in its user session
• Language is set by the language header in the web request to the first requested language matching one of the available languages,
• In other cases the default language is returned

Some older services still use /srv/{lang}/service convention to request a language (using the 3 letter code), this should be considered similar as the ?l={lang} parameter (using 2-5 letter code).

Fall back mechanisms when translations are missing or not complete

In general 2 cases of fall-back exist:

A language file in the requested language is not available.

This case should not cause a ajax request returning 404 file not found. Instead call a service locating the file, and if it does not exit, returns an empty document. Better approach is to grab all relevant language files and merge it into a single file to limit the number of requests.

A translation for the requested key in the current language is empty or not found

Optimal approach is to fall-back to a configurable second (or third) language which is likely to have the key. If configuration is not an option, English is the most like candidate as a fall back language. Since we're not using human-friendly keys from version 4+, displaying the untranslated key is not an option anymore. It would be optimal if the application can log a warning to the logs about the missing translation. A client application would need to preload the current language and fall-back language(s) in order to be able to fall-back.

Technical errors should not be translated

A user should be enabled to copy-paste a technical error as-is into a search engine. If the message is translated, (s)he will probably not find the most relevant matches.