Skip to content

Translations

Sam Rust edited this page Oct 14, 2020 · 23 revisions

Overview

DMPRoadmap uses the translation gem for managing internationalization. The translation gem manages both the Gettext and I18n translations. The Gettext files are located in config/locale and consist of a master app.pot file and separate [language_code]/app.po files for each translation. If a client domain is specified, there will be additional client.pot and client.po files within those directories.

Several of the gems we use however continue to use the standard Rails I18n system so their specific translations files continue to reside in the config/locales/ directory.

Every language must have corresponding files for Gettext and I18n.

For a list of currently supported languages, please refer to the ./config/locale directory.

How DMPRoadmap will manage translations

Since the move over to translation.io means the tooling for maintaining the translations is much easier to use, the DMPRoadmap team will be taking a more active role in managing those translations and making them available to the community.

When new strings will be uploaded to Translation.io

Before each code-release which involves changes to the text within DMPRoadmap, we will re-sync the translation strings available in translation.io. Each string will also be run through google-translate to provide a stub-translation for each supported language. At this point, these strings, along with the stub-translations, will be available to translators within the translation.io tool.

When new translations will be made available via DMPRoadmap.

We will start using point-releases to make translations available to the community. Once translators have updated the strings within translation.io, these will be synced-down to the DMPRoadmap codebase, and a tagged-release created. You can also let us know that you'd like us to re-sync these and create a release by creating a ticket on this repository.

Getting Started as a Translator

In order to start contributing to the translation of DMPRoadmap, our team will need to get you setup as a translator on our project on translation.io. Please reach out to [email protected] and let us know the email-address you'd like to use for the account, as well as which languages you'd like to translate, and we can grant translator permissions.

Requesting Additional Languages

The current set of languages being maintained for the DMPRoadmap project is [de en-CA en-GB en-US es fi fr-CA fr-FR pt-BR sv-FI]. In order to request additional target languages are added to the codebase (and to translation.io), please open an issue on this repository with the pertinent details.

Configuring your localization

The configuration for the new translation gem is in config/initializers/translation.rb. The first block enables two different sets of translation strings through the concept of a "domain". The default, "app" domain will be managed by the DMPRoadmap team, with new translations being distributed via point-releases as described above. The secondary, "client", domain can be used to manage localization of your customization to the DMPRoadmap codebase. An environment variable, DOMAIN can be set to either "app" or "client" to determine which set of translations rake-tasks will interact with. When running the application, DOMAIN should either be un-set, or be set to "app". The app domain is setup to first check for a translation in the app, and then check in your client translations if a match cannot be found. You can also manage which target-locales are available while your application is running. These are set in the config.target_locales, and must match a Language.abbreviation from your database in order to work in the running application.

Adding your client domain.

We have also provided an example configuration for a client-domain which will allow you to localize any custom-text you have added to the tool. Within the ENV["DOMAIN"]=="client" block, you'll be able to customize the behavior of this domain, setting it's source_locale, target_locales, and the directory(s) which will be searched for translation keys. You may also choose to use translation.io to manage these translations and allow remote collaborators to translate. In this case, you'll need to create an account and setup a new translation project. After doing so, you'll be given an API key which you can set to the environment variable TRANSLATION_API_CLIENT. Now, with both the TRANSLATION_API_CLIENT and DOMAN=client variables set, you'll be able to use the rake tasks from the translation gem to initialize your project on translation.io and sync your keys and translations.

Standards

You should use the ISO 639-1 language codes when creating a new translation. If you need/want to create a country specific variation for one of the ISO 639 macro-languages you should use the ISO 3166 2 character alpha codes to designate the country/region.

For example en is the ISO 639 code for English and en-US and en-GB are the ISO 3166 country code specific variations for the United States and Great Britain. If you are uncertain which code to use, please contact the DMPRoadmap project team.

Please note that Gettext uses an underscore for its file names and not a dash (e.g. en_GB instead of en-GB). The translation gem will convert between the Gettext and I18n styles of language-abbreviation.

Clone this wiki locally