Translation guidelines

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 keys. A key should be specific enough so a developer can identify to what component it refers. Consider that transifex does not display the keys, but only the translated value in the default language (english).

For future versions of the software (4+) we are leaving the aspect 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).