Apostrophe Import Export Translation

This module enables import and export of site text as a JSON file for translation.

Purpose

The purpose of this module is to create a specialized JSON file containing the text of the site, which can be downloaded and manually edited into a different language before being imported into a new locale. Upon import, pages from the default locale will be localized into the new locale substituting the translated text.

Installation

To install the module and the required dependencies, use the command line to run this command in an Apostrophe project's root directory:

npm install @apostrophecms-pro/import-export-translation @apostrophecms-pro/automatic-translation

If you already have the automatic-translations module installed, make sure you have at least the minimum required version:

{
  "@apostrophecms-pro/automatic-translation": "^1.2.0"
}

Usage

Configure the module in the app.js file:

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    '@apostrophecms-pro/automatic-translation': {
      options: {
        enabled: false
      }
    },
    '@apostrophecms-pro/import-export-translation': {}
  }
});

WARNING: The @apostrophecms-pro/automatic-translation module is required for the module to work. If you already have it configured in your project, you have to explicitly set the enabled option to false in the existing configuration in the app.js file.

How to use the Import Export Translation module

The Import Export Translation module adds a new button to the admin bar (see below). Click on the button to open a modal window with options to import or export the locale text.

Export

To export text from the default locale, make sure that locale is active and click on the "Export Translation" button. A new modal window will open with the options to select between exporting all documents or only the documents that have been modified since the last export. Note that the last export date is shown in the modal description section. Click on the "Export Translation" button to download the JSON file.

This file can then be duplicated for each desired locale language. Only the "text" string values should be altered, the rest of the data in the file should remain unchanged in order for the text to be imported correctly. This is covered in the JSON data structure section.

Import

To import translations, first switch to the locale where you want to import a translation file. Then click on the "Import Translation" button from the initial dialog. A new modal window will open with the options to select a JSON file to import. This file should be a previously exported JSON file, with translated text. Click on the "Import Translation" button to import the text and localize documents from the default locale.

How it works

The Import Export Translation module brings a specific workflow to ApostropheCMS. It allows you to export text from the default locale to a JSON file. This file can then be translated by a third-party service or manually. Once the translation is done, you can import the translated text back to a target locale. Keep in mind that the source and target locales shouldn't be the same. The module creates or updates existing documents in the target locale, using the published documents from the source locale. Importantly, archiving or unpublishing any pages, pieces or related documents, like images, between JSON file export and then import into the new locale can cause errors. You do not have to localize pages to the target locale first. Any pages that have been localized already will be overwritten by the imported translations. This means any newer changes that have been made to pages in the target locale will be lost. This also explains why the module doesn't allow importing translations to the same locale it was exported from - this would lead to losing any new edits for the locale.

A quick example workflow would be:

1. Export text from the en locale.
2. Translate the string values to French.
3. Import the translated text to the fr locale.

In this case, the fr locale is entirely managed by the Import Export Translation module and will be based on the published documents from the en locale. The French locale should not be edited manually prior to the import.

JSON data structure

Here is an example JSON file exported by the module:

{
  "version": "1.0",
  "locale": "en",
  "exportedAt": "2024-08-14T14:25:37.265Z",
  "documents": [
    {
      "_id": "ebbbayuxv8y52lkj1hzu8ii1:en:published",
      "type": "article",
      "data": [
        {
          "text": "article 1",
          "hint": "Title",
          "system": {...}
        },
        {
          "text": "article 1",
          "hint": "Slug",
          "system": {...}
        },
        {
          "text": "<p>A rich text content: article1</p>",
          "hint": "Main > Rich Text",
          "system": {...}
        }
      ]
    },
    {
      "_id": "eczrqxxb8nz9pu2plqb0gaj1:en:published",
      "type": "@apostrophecms/home-page",
      "data": [
        {
          "text": "Home",
          "hint": "Title",
          "system": {...}
        }
      ]
    },
  ]
}

All documents are stored in the documents array. Each document has the following properties:

• _id: The document ID
• type: The document type
• data: An array of fields with the following properties:
  • text: The text value that should be translated
  • hint: A hint extracted from the field schema - field translationHint or label property value in format of "Parent Field Label > Field Label" (see below for more details)
  • system: System data that should not be modified, used to apply the translation back to the document

Translation hints

As mentioned in the previous section, the module adds a translation hint as context beside the text to be translated. The hint is extracted from the field schema translationHint property. If the translationHint is not defined, it will use the label property as a fallback. When the field is nested, the hint will be in the format of "Parent Field Hint > Field Hint" (e.g. "Main > Rich Text").

When the current or parent field is a widget, the same logic for the schema fields is applied, but the hint will be extracted from the widget options - widgetModule.options.translationHint or widgetModule.options.label properties.