search

Cimpress / cimpress-translations-webpack-plugin

Advanced Webpack integration with Cimpress' Translations service
4 stars 2 forks source link

Support synchronisation of local translation files to Cimpress' translations service #5

Open akincel opened 6 years ago

akincel commented 6 years ago

We would like to support our use case and also make it a recommended way on how to use Cimpress's translations service. The steps are the following:

  1. Have one of the language files (e.g., your primary language file) versioned locally in your project repository. The file is used to add new translation keys for the service. This file can be reviewed during the regular pull request review process.
  2. All the other language files are stored in the translations service.
  3. After a pull request which changes the locally stored language file is merged, the language file is used as a source of truth to update the translations service. This is performed during the build process.
  4. As the next step of the build process, the translations webpack plugin pulls the language files and incorporates them into the current application version. This will already include the updated "main" language file.
  5. Translators can now utilize the Cimpress Translation UI to add translations for other languages. The translations they made will be included in the next build of the application.

To make this happen, we propose that the cimpress-translations-webpack-plugin should support step 3. The process of the step can be the following:

  1. There is a configuration saying when this process should be executed (as we would like it to happen only on merge to master, not on every webpack build).
  2. The plugin calls Cimpress' translation service in order to retrieve the remote version of the locally versioned translation file.
  3. The plugin diffs the remote version and the local changed version of the translation file and generates a structure patch (adding/removing keys)
  4. The plugin calls Cimpress' translation service in order to patch the structure. For that the client needs to add support for the structure patch endpoint (https://github.com/Cimpress/cimpress-translations/issues/3).
  5. The plugin calls Cimpress' translation service in order to store the blob of the locally versioned translation file (https://github.com/Cimpress/cimpress-translations/issues/6).
Igrom commented 6 years ago

The combined purpose of steps 4 and 5 in the second deliberation is unclear to me. Could you elaborate?

Each step features a call to the Translations service. Do they modify the same blob?

akincel commented 6 years ago

There are 2 different resources in Translations service:

The structure dictates what keys can be translated and it also adds context (human-readable name, description) to the keys. An individual blob can be viewed as a materialization of the structure.

Therefore, there are 2 separate steps needed:

  1. Update the structure by adding/removing keys
  2. Replace the blob with the recent version

While I agree that by updating the blob we can automatically add/remove keys from the structure it is not optimal from the Translations service API standpoint. Imagine a situation when someone adds blob for a new language which only has a few keys translated. That will trigger the update of the structure and thus deletion of all keys which were not present in the blob.

That's why Translations service introduced a separate endpoint for patching the structure. In the future, the blobs might also be validated against the structure. Then if you try to add a blob which is not valid against the structure it will be refused by the service.

Does that make more sense now?