How to add internationalization to your project

There are several factors to adding internationalization capabilities to a project.

You might have to create a project in OneSky to store the translations that belong to your project. You might have to consume translations that are global to all Doodle projects too.

In any case, it's good to present an overview of what parts are involved in these processes before running any command so that you can grasp what things are running in the background and where/what to look for if something goes wrong.

OneSky administration (website part)

In order to log into OneSky, you need to get the credentials from somewhere (lastpass). Once this is done, you'll need to create a new project:

• Select Regular Web App as a project type

• Select English as base language

• Later, you'll have to manually input one key in order to be able to continue creating the project. Just add one random key value pair that you will remove immediately after project creation.

• In the multiple select translate to: select the following:

da, de, en, en_GB, es, fr, it, nl, no, pt_BR, fi, sv

• Click Create project

And voilà, your new project is live!

OneSky administration (local project part)

Now, you need to set up your project to communicate with OneSky properly.

Your project needs a couple of files:

• .oneskyrc at the top level folder which contains something like:

  {
    "projectId": "141403",
    "fileName": "translations.json",
    "format": "HIERARCHICAL_JSON",
    "keepStrings": true,
    "dependentProjectIds": ["141403", "140993"]
  }
  

  NOTE: when moving keys from one parent to another set "keepStrings": "false", to remove deleted keys

  Where:

  • projectId is the value used to determine what project to upload translations to.
  • dependentProjectIds is the value used to determine what projects to download translations from. Example: @doodle/common-messages: 141403 and @doodle/users-api-connector: 140993

• .env at the top level folder which contains something like:

  MY_OTHER_ENVIRONMENT_VARIABLE=bacon
  ONESKY_PUBLIC_KEY=lalalallelelelolololululu
  ONESKY_SECRET_KEY=20349bdcjkdh238edsfuisnd2
  

  These two keys (ONESKY_PUBLIC_KEY, ONESKY_SECRET_KEY) are necessary in order to both upload AND download translations.

  In your gulpfile.js:

  // eslint-disable-next-line global-require
  require('dotenv').config(); //required for using credentials from .env
  const onesky = require("@doodle/i18n/dist/onesky");
  
  /**
   * Upload messages to Onesky for default language
   */
  gulp.task("i18n:upload", async () => {
    onesky.uploadBaseMessagesFromSource();
  });
  
  /**
   * Upload messages to Onesky for all languages
   */
  gulp.task("i18n:upload:all", async () => {
    onesky.uploadAllTranslations();
  });
  
  /**
   * Upload messages to Onesky
   */
  gulp.task("i18n:update", async () => {
    onesky.updateTranslations({ includeValues: true });
  });
  
  /**
   * Download messages from Onesky from project merged with messages from dependentProjectIds
   */
  gulp.task("i18n:download:merged", async () => {
    const result = await onesky.downloadAllTranslations({
      i18nPath: "./i18n/merged"
    });
  });
  
  /**
   * Download messages from Onesky from single project
   */
  gulp.task("i18n:download", async () => {
    onesky.downloadAllTranslations({ dependentProjectIds: [] });
  });
  

• This module can also work with @doodle/vault instead of the ONESKY_SECRET_KEY and ONESKY_PUBLIC_KEY environment variables.

  vault login -method github
  # Enter your GitHub developer access token with `read:org` permissions
  yarn add @doodle/i18n @doodle/vault
  

  In your gulpfile.js:

  const { Vault, getToken } = require("@doodle/vault");
  const onesky = require("@doodle/i18n/dist/onesky");
  
  const getOneSkyCredentials = async () => {
    const token = await getToken({});
    const vault = Vault({ token });
    const { data: credentials } = await vault.read(
      "secret/doodle/staging/onesky/credentials"
    );
    return credentials;
  };
  
  /**
   * Upload messages to Onesky for default language
   */
  gulp.task("i18n:upload", async () => {
    const credentials = await getOneSkyCredentials();
    onesky.uploadBaseMessagesFromSource({ credentials });
  });
  
  /**
   * Upload messages to Onesky for all languages
   */
  gulp.task("i18n:upload:all", async () => {
    const credentials = await getOneSkyCredentials();
    onesky.uploadAllTranslations({ credentials });
  });
  
  /**
   * Upload messages to Onesky
   */
  gulp.task("i18n:update", async () => {
    const credentials = await getOneSkyCredentials();
    onesky.updateTranslations({ credentials, includeValues: true });
  });
  
  /**
   * Download messages from Onesky from project merged with messages from dependentProjectIds
   */
  gulp.task("i18n:download:merged", async () => {
    const credentials = await getOneSkyCredentials();
    await onesky.downloadAllTranslations({
      credentials,
      i18nPath: "./i18n/merged"
    });
  });
  
  /**
   * Download messages from Onesky from single project
   */
  gulp.task("i18n:download", async () => {
    const credentials = await getOneSkyCredentials();
    onesky.downloadAllTranslations({ credentials, dependentProjectIds: [] });
  });
  

Keys that are local to your project

Create a messages.js file per component you want to translate and put it in the component's folder.

It will look like something like this:

import { defineMessages } from 'react-intl';

export default defineMessages({
  createADoodle: {
    id: 'contentProxy.components.SiteHeader.createADoodle',
    defaultMessage: 'Create a Doodle',
  },
});

Upload them to OneSky with the gulp task:

gulp i18n:upload

Keys that are global for all Doodle projects

Download them from OneSky with the gulp task:

gulp i18n:download