@ace-de/eua-translations-sync v2.1.8-alpha.1

Translation sync package (@ace-de/eua-wa-lib/eua-translation-sync)

This package allows us to sync translations in relation: local translation files <-> corresponding Google Spreadsheet. Sync can be triggered manually or automatically.

We're using two types of scripts:

1. Push script

$ npm run push:i18n # add new translation tokens with their values, wouldn't chane existing tokens and their values
$ npm run push:i18n --replace-modified # changed token value from JSON file update in GSheet document 
$ npm run push:i18n --cleanup-tokens # remove tokens from GSheet document if don't exist in JSON file 

2. Pull script

$ npm run pull:i18n # overwrite JSON token value with value from GSheet, don't change token keys in local JSON 
$ npm run pull:i18n --get-new-tokens # add tokens to local JSON if GSheet document has a new tokens

Manually triggered sync

In order to manually start translation sync, app's package.json must contain following scripts:

"push:i18n": "translations-sync push",
"pull:i18n": "translations-sync pull"

Also, we need Google Sheet API and spreadsheet credentials stored in .env file:

GOOGLE_SPREADSHEET_ID= can be extracted from the URL --> https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0
GOOGLE_SHEET_ID= can be extracetd from the URL --> https://docs.google.com/spreadsheets/d/aBC-123_xYz/edit#gid=sheetId 
GOOGLE_SHEET_NAME= name of sheet that corresponds to sheetId
GOOGLE_SERVICE_ACCOUNT_EMAIL= service account's email, created on Google Cloud (https://cloud.google.com/iam/docs/service-account-overview) and specific for each app
GOOGLE_PRIVATE_KEY= private key of the created service account
LOCALE_TRANSLATION_EN_US_PATH=
LOCALE_TRANSLATION_DE_DE_PATH=

For manual sync we should follow these steps in the specified order: 1. If we have new translation keys with values in local files, execute push script

npm run push:i18n

2. Run pull script for getting and writing all changes from defined sheet into local files

npm run pull:i18n --get-new-tokens

3. Go through changes in local files (created after pull script completion) and carefully determine what changes should be preserved and what should be reverted
4. If some translation keys' values were changed, run following command in order to make the same changes in the sheet:

npm run push:i18n --replace-modified

5. If we removed some translation keys from the local files, we should reflect it on corresponding sheet by running:

npm run push:i18n --cleanup-tokens

At this point everything should be synced and local files should be 1:1 with the corresponding sheet.

Automatically triggered sync

On version change

On each app's version change, automatic sync can be triggered by extending package.json's scripts with:

"preversion": "translations-sync",

For the automation to work, we need reduced version of the .env file, with no specified sheets' IDs and names, as we're getting those from spreadsheet itself:

GOOGLE_SPREADSHEET_ID=
GOOGLE_SERVICE_ACCOUNT_EMAIL=
GOOGLE_PRIVATE_KEY=
LOCALE_TRANSLATION_EN_US_PATH=
LOCALE_TRANSLATION_DE_DE_PATH=
LOCALE_TRANSLATIONS_PATH= path to the directory of the local translation files

The consequence is that on each version increase with command npm version some-version translation sync is triggered and following is executed:

• getting current (new) app version
• determining sheet that should be updated --> if version is alpha version, sync is done for DEV and INT sheets, otherwise we're syncing with PP sheet
• getting git differences between current and previous version --> all translation changes found within git diff have priority over changes in spreadsheet
• if new translation keys are found within git diff, push script for adding new keys with its values into specified sheet is triggered
• running pull script for getting all changes from the specified sheet and writing those changes into local files (this step is always triggered) --> local values are replaced only in a case when those changes are not in a conflict with changes from git diff (local changes made between the last two versions have priority)
• if git diff detects removed translation keys or changes of their values, push script for removing tokens and changing tokens' values (--replace-modified and --cleanup-tokens) on specified sheet is triggered
• checking if pull script made some changes within local files
• commiting and pushing changes to the origin/current-branch, if changes exist

At this point local files should be 1:1 with the corresponding sheet and changes commited and pushed to the origin.

On release branch merge into master

When merging release branch into master branch we can trigger translation sync by running following command:

sync-merge:i18n release-x

This command must be defined in the app, by adding it into package.json's scripts:

scripts: {
...
"sync-merge:i18n": "merge-with-translations-sync"
}

Once we run this script, it'll do the following:

• Search for defined release branch and check if current branch is master branch.
• Check out on defined release branch.
• Start sync process for PROD environment -->
  • pushing only new tokens to PROD sheet
  • pulling all changes from PROD sheet
  • committing and pushing changes to origin/release-x
• Check out back on master branch
• Merge synced origin/release-x branch into master (git merge --no-ff origin/release-x)

Missing LOCALE_TRANSLATIONS_PATH among env variables

If for some reason we don't have LOCALE_TRANSLATIONS_PATH variable in our local .env file, translation sync will not be performed. However, version will be increased anyway. As automated translation sync depends on git differences between the last app's version and current HEAD, we're no longer able to start automated translation sync with intention to include translation changes from the previous version, as no git differences will be recognised. Therefore, we must first run sync manually in order to include all missed translations from the previous version. After that, with assumption that missing variable is included, first next version increment should perform automated translation sync.