Add support for a new language on GOV.UK
To add support for a new language on GOV.UK, two things are required before any development work can begin.
- The correct language tag must be provided
- Translated locale files must be provided
Language tag
The language tag should be compatible with the IETF Language Tag syntax and use correct ISO 639 codes (with optional ISO 15924 or ISO 3166 subtags where appropriate). This is important to ensure maximum compatibility with accessibility features such as screen readers. Some other useful reading includes Rails Translation Manager and Whitehall Internationalisation guide.
Obtaining translations for internationalised strings
At the time of writing, there are four codebases where we store internationalised strings. These are:
Developers must export a csv containing all internationalised strings from frontend, government-frontend and govuk-publishing-components to be sent to the translator. Documentation on how to do this is available in Rails translation manager.
Check if the new language is already supported by the Rails framework by looking for your language tag in the rails locale folder. If it’s not supported, translations will also be needed for govuk-app-config. The internationalised strings that Rails requires contain a lot of interpolation, which has proved challenging for translators to understand. There is a template csv file that contains instructions for translators which can be used for the govuk-app-config translations.
Once translations have been obtained from the translators, publishing and rendering applications can be updated via the following steps:
Do not complete steps 3, 4 and 5 before steps 1 and 2 have been completed. This can cause failures in our CI/CD when the frontend rendering applications are asked to render content for all the locales publishable by whitehall.
1. Add support for your new language to the frontend rendering applications
At the time of writing, Whitehall content is rendered by either Frontend or Government Frontend. So both applications must be updated.
- Add the new language tag to
config/application.rb
andconfig/locales/en.yml
in alphabetical order - From within frontend, or government frontend, create a folder
tmp/locale_file
- Add your csv from the translator to this folder. The name of the csv should be in the format:
<new_locale>.csv
, egky.csv
Run the following commands to import your csv, and create a new locale file.
$ rake translation:import_all
In
config/locales/<new_locale>.yml
add the language translation under thelanguage_names
key.For example:
it: language_names: it: italiano
2. Add support for your new language to govuk-publishing-components
Follow steps 2, 3 and 4 from the previous section from within the govuk-publishing-components repo.
3. Update Whitehall
You will need the language’s:
- English name (e.g. Welsh)
- Native name (e.g. Cymraeg)
- Text direction (ltr or rtl)
4. Update Publishing API
- Edit
content_schemas/formats/shared/definitions/locale.jsonnet
andconfig/application.rb
in alphabetical order - Run
rake build_schemas
to generate all the schemas
5. Update Content Store
- Add the locale key to
config/application.rb
in alphabetical order