Link Search Menu Expand Document
Next Right Now

How to use Locize

The content displayed on NRN is translated using different ways, depending on where the translations are stored:

  1. Dynamic i18n - Content-related (e.g: Post title in FR + EN). It will depend on your data and how you fetch those data (real-time SSR, SSG, etc.)
  2. Static content - Locize (fetched from Locize API). This content can be updated through Locize backoffice, or when using in-context editor.

Table of contents

Overview

How to use Locize in-context editor?

You can enable Locize in-context editor mode, by appending ?locize=true to the url, see https://nrn-default.now.sh/?locize=true

Note that it’s only enabled in development and staging stages, not in production.

Fetching translations through Locize provider

When the content we want to display doesn’t come from GraphCMS API, then it’s considered as a “static” content.

This means that the content is managed by Locize and must be updated manually there.

Check this video to see Locize in action with react-i18next.

Locize translation workflow in-depth

The Locize project contains two different versions:

  • latest: This Locize version is used in any non-production application stage (development, staging). That’s where translations get added/updated by translators.
  • production: This Locize version is only used in the production application stages (NEXT_PUBLIC_APP_STAGE=production) (all customers share the same production version in the current setup, for the sake of simplicity)

This separation between the two versions is important and very useful to avoid deploying unapproved changes to the production stage.

In order to update the production version, all changes must go through the latest version. They can therefore be tested during the development phase, then during the staging phase. Once you’re ready to ship the content to production, the production version can be updated from the latest version, which will automatically update all customer production stages.

Tip: New i18n keys are added automatically in the development stage, as they are being added to the source code, thanks to the saveMissing option. This can also be a bit boring with HMR, because useless keys may be created while programming.

Custom “per-customer” variation (namespace)

It is possible to create per-customer Locize namespaces to store translations that are related to one customer, and only use those for that customer.

Assuming you have the following Locize namespaces in your project:

  • fr
  • en

You can create the following namespaces:

  • fr-x-customer1
  • en-x-customer1

x stands for “custom variation”. In Locize language, a “namespace” is a “localization variation”.

Once those namespaces have been created, you can simply override any sentence you want, and it will apply only to this customer, instead of the sentence configured in the fallback language (fr, en).

You do not need to translate all sentences again, only those you wish to be different for this customer. Sentences will automatically fall back to the language namespace if no translation is found in the customer namespace.

How does it work?

There is no magic behind it, NRN simply always fetches the variations for the customer, alongside the language namespaces.

If no variation namespace is found then nothing particular is done. But, if a variation namespace does exist (e.g: fr-x-customer1) then it’ll merge all translations from fr and fr-x-customer1 namespaces.

Locize additional services

Locize provides a few additional services. Some are free, some are paid.

Other additional services

  • One interesting thing is the ability to share part of the project to be translated by a third party using Crowdbased, without sharing the whole project.
  • There are also several paid Translation services, where you can pay people to translate your content.
  • It is also possible to enable Audit, which allows to audit every change to our translations, and keep changes up to 10 years. (expensive)

Dependencies

We rely on those packages to manage the translations:

  • i18next-locize-backend: This is an i18next backend to be used for locize service. It will load resources from locize server using xhr. It will allow you to save missing keys containing both default value and context information This backend is used when using the browser.
  • i18next-node-locize-backend: This is a i18next backend to be used with node.js for the locize service. It’s for the node.js server what the i18next-locize-backend is for the browser. This backend is used when using node (server).
  • locize-editor: The locize-editor enables you to directly connect content from your website / application with your content on your localization project on locize. Enabling the editor by querystring ?locize=true you can click any text content on your website to open it on the right side editor window This plugin is used when using the browser.
  • locize-node-lastused: This is an i18next plugin or standalone scriot to be used for locize service. It will update last used timestamps on reference keys from your locize project using xhr. It sets the last used date on your reference language’s namespaces. This plugin is used when using node (server).

It was quite complicated to configure Next with Locize, mostly because of the universal way Next works, while Locize has dedicated packages depending on the runtime engine.

See src/utils/i18nextLocize.ts to see how it was all put together.

We were inspired by this SO question.

Resources