Managing language content

It is possible to amend all text copy in OpenCRVS and introduce as as many content translations as you like.

Technical background

The multi-lingual text content approach for OpenCRVS is developed using FormatJS . It is worthwhile reading their documentation to understand how this technically works, particularly this page.

FormatJS uses industry-wide i18n JSON standards to import text content. This JSON standard is also exported by enterprise level content management systems such as Transifex or Contentful.

If you are not using a content management system, you edit text copy directly in these JSON files that are served to the client. Therefore, you will need a code editor like VSCode, explained in step 3.1.5 Tooling.

Editing text content

You can edit copy at any time, even after OpenCRVS goes live. The code to serve this JSON to the application is provided in the country configuration repo and requires no configuration in order to serve.

The content JSON looks like this:

  "data": [
      "lang": "en",
      "displayName": "English",
      "messages": {
        "buttons.add": "Add",
        "buttons.apply": "Apply",

You can duplicate the JSON Object blocks in the "data" array for every language you want to support. Duplicate the entire block. In our Farajaland example you can see that we have duplicated the block for French.

  • The lang key is an ISO 639-1 language code

  • The displayName is how you want this language selection to be displayed in the user language select component in a content management system.

  • Inside the messages object are all the possible content keys that OpenCRVS uses. You can edit the value but not the key itself. You must not remove any keys as they are ALL required.

  • The value uses the unicode ICU Message Syntax approach using braces {} and English variables to occasionally substitute dynamic text. You must read the unicode documentation and understand how this works if you are editing these values. Dynamic variables must remain in English.

  1. Edit text for the client application in JSON in this file: client.json. The descriptions for the use-case of each of these client content keys is described in this JSON file.

  2. Edit text for the login application in JSON in this file: login.json . The descriptions for the use-case of each of these login content keys is described in this JSON file.

  3. Edit SMS notifications JSON in this file: notifications.json . The descriptions for the use-case of each of these SMS notifications content keys is described in this JSON file.

Some dynamc content is rendered using ICU Message Syntax, explained here: https://formatjs.io/docs/core-concepts/icu-syntax\

For example, in cases like the below, the areas in bold are the areas to translate and you leave the rest of the syntax in English as it is code:

{year}-Farajaland-{event, select, birth{birth} death{death} other{birth}}-event-statistics.csv {fileSize} This is the most complex example:

{event, select, declaration {{eventType, select, birth {birth} death {death} other{birth}} declaration has been sent for review.} registration {{eventType, select, birth {birth} death {death} other{birth}} has been registered.} duplication {{eventType, select, birth {birth} death {death} other{birth}} has been registered.} rejection {{eventType, select, birth {birth} death {death} other{birth}} declaration has been rejected.} certificate {{eventType, select, birth {birth} death {death} other{birth}} certificate has been completed.} offline {{eventType, select, birth {birth} death {death} other{birth}} declaration will be sent when you reconnect.} other {{eventType, select, birth {birth} death {death} other{birth}}}

After editing the content, if the JSON is not valid, it will not load properly in the client. You can use an online validator like this one to check that your JSON is valid. VSCode also warns you by highlighting any errors.

Setting up a content management system

It requires professional expertise in NodeJS if you want to set up a content management system other than Contentful.

You can see the functions that decide to serve either the static JSON text files or JSON from Contentful here. If you want to use a different system, you can code whatever integration you like in the getLanguages function provided it returns language JSON to the clients in the same format as the static JSON files.

Update this environment variable to enable a content management system appropriately.

If you are using Contentful we automatically export JSON files ready for Contentful import if you wish to use it.

To perform an initial import to Contentful:

  1. First create a space in Contentful and add your locales for your translations. Copy your space-id from Contentful settings.

  2. Download and install the Contentful cli

  3. Run the following command to export your space as you will need ids for your locales: contentful space export --space-id=<your-space-id>

  4. Open the exported file and copy the required ids to this file

  5. You can run the following command to generate a contentful-import.json file: yarn contentful:prepare:import

  6. Run the Contentful import script: contentful space import --content-file src/features/languages/generated/contentful-import.json --space-id=<your-space-id>

  7. Get your API key from Contentful settings and add it to an environment variable .env file, or paste here for use in development. DO NOT SUBMIT API KEYS TO A PUBLIC REPO!

Last updated