Skip to main content

Translating UI Messages

Most content that needs to be translated is in Markdown files in translation repos. However, Gatsbyjs.org also has several pieces of UI text that should be translated using a library called Lingui.

Message Translation Guide

Unlike Markdown documents, UI messages are kept in the same monorepo as the gatsby source.

  1. Follow the instructions for running the Gatsby website.
  2. Go to www/ and run yarn lingui:add-locale [lang code] to generate a file for your language at src/data/locales/[lang-code]/messages.po.
  3. Translate all the strings in [lang code]/messages.po by editing the msgstr field of each message.

Translating rich content

Some messages will have embedded numerical tags in them. These represent embedded components, formatting, or user-defined text and should be kept in the translated string. If you are unsure about the context of a tag, make sure to look at the source file of the message.

The sections below list the different types of rich content you may encounter.

Self-closing tags

This type of rich text consists of a single self-closing XML tag (e.g. <0/>):

These are usually icons embedded in the text:

If you are translating a right-to-left language like Arabic, make sure the icons are in the proper position at the start or end of the text.

Opening and closing tags

This type of rich text consists of matching XML tags (e.g. <0> and </0>):

These can represent formatting, accessible text, or links:

Make sure that the tags are paired correctly and surround the corresponding text in the translation.

Interpolated text

This rich text is represented by braces and a number (e.g. {0}):

These represent text in interpolated strings:

Plurals, formatting, and grammatical gender

Right now, no text with complex formatting rules is available for translation. When it is, this guide will be updated.

Updating content

Sometimes additional content is added to the UI, leading to untranslated text. When this occurs, please update your language’s messages.po file with the new translations.

New messages

New messages can be found by searching for msgstr: "". These messages may be translated as usual.

Updated message text

If a previously translated UI message has changed, Lingui will mark that message as outdated and create a new entry for the updated text:

Translate the updated entry and delete the old one:


Edit this page on GitHubLast updated: