Skip to main content
  1. Home
  2. Publishing
Last updated: 28 May 2025

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.

  1. The correct language tag must be provided
  2. 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.

Example PR in government

  1. Add the new language tag to config/application.rb and config/locales/en.yml in alphabetical order
  2. From within frontend, or government frontend, create a folder tmp/locale_file
  3. Add your csv from the translator to this folder. The name of the csv should be in the format: <new_locale>.csv, eg ky.csv

  4. Run the following commands to import your csv, and create a new locale file.

    $ rake translation:import_all

  5. In config/locales/<new_locale>.yml add the language translation under the language_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

Example PR

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

Example PR

  1. Edit content_schemas/formats/shared/definitions/locale.jsonnet and config/application.rb in alphabetical order
  2. Run rake build_schemas to generate all the schemas

5. Update Content Store

Example PR

  • Add the locale key to config/application.rb in alphabetical order

More in the Publishing section

Learn

How to...