Translations Plugin
Relevant source files
The following files were used as context for generating this wiki page:
- packages/translations/README.md
- packages/translations/src/plugins/plugin.ts
- packages/translations/src/providers/traduora.provider.ts
- packages/translations/src/providers/poeditor.provider.ts
- packages/translations/src/providers/transifex.provider.ts
- packages/translations/src/providers/simplelocalize.provider.ts
- packages/translations/src/executors/extract/schema.json
- packages/translations/src/generators/add/add.impl.ts
- e2e/translations-e2e/tests/translations.spec.ts
The Translations Plugin provides a comprehensive toolkit for managing internationalization within an Nx workspace. It specifically targets FormatJS and React Intl projects to automate the lifecycle of translation strings.
This plugin automates four primary tasks: extracting messages from source code, pushing strings to external translation platforms, pulling translated content back into the project, and performing automatic machine translation. It supports multiple third-party providers including Traduora, POEditor, Transifex, and SimpleLocalize.
Sources: packages/translations/README.md:1-12, packages/translations/package.json:14-23
Plugin Architecture
The plugin integrates into the Nx project graph by detecting .translationsrc.json files. When a project contains this configuration file, the plugin automatically generates corresponding Nx targets.
This diagram shows how the presence of a configuration file triggers the generation of Nx targets mapped to specific executors.
Sources: packages/translations/src/plugins/plugin.ts:21-42, packages/translations/src/plugins/plugin.ts:98-112
Automatic Node Creation
The plugin uses createNodesV2 to scan the workspace for **/.translationsrc.json. It skips project creation if the directory does not contain a project.json file.
Sources: packages/translations/src/plugins/plugin.ts:21-49
Configuration
The plugin uses a hierarchical configuration system where a project-level .translationsrc.json can extend a root-level configuration.
Root Configuration Options
Root options define global settings for all projects in the workspace.
| Option | Type | Description |
|---|---|---|
provider | string | The external platform (e.g., traduora, simplelocalize). |
outputDirectory | string | Directory where translation files are stored. |
defaultLanguage | string | The source language code (e.g., en). |
languages | string[] | List of all supported target language codes. |
translator | string | Service for auto-translation (e.g., deepl, google). |
autoTranslate | boolean | Enables automatic translation during the push process. |
Sources: packages/translations/README.md:83-95, packages/translations/src/executors/extract/schema.json:7-40
Project Configuration
Project-specific settings link individual Nx projects to their counterparts in translation providers.
{
"extends": "../.translationsrc.json",
"projectName": "my-web-app",
"projectId": "external-platform-id"
}
Sources: packages/translations/README.md:37-41, packages/translations/src/generators/add/add.impl.ts:63-66
Core Executors
Extraction
The extract executor scans source files for FormatJS components like <FormattedMessage /> or intl.formatMessage(). It identifies strings based on a configurable pattern and generates JSON or YAML files in the output directory.
Sources: packages/translations/src/executors/extract/schema.json:15-58, e2e/translations-e2e/tests/translations.spec.ts:58-92
Translation Providers
The plugin uses a provider-based architecture to interact with various APIs. Every provider extends a BaseProvider class.
This diagram illustrates the inheritance structure for external translation service integrations.
Sources: packages/translations/src/providers/traduora.provider.ts:12-14, packages/translations/src/providers/poeditor.provider.ts:11-13, packages/translations/src/providers/transifex.provider.ts:23-25, packages/translations/src/providers/simplelocalize.provider.ts:18-20
Provider Capabilities
- Traduora: Manages terms and translations via bearer token authentication. It automatically creates projects if they do not exist. Sources: packages/translations/src/providers/traduora.provider.ts:83-125
- POEditor: Synchronizes terms using a sync API and handles reference languages. Sources: packages/translations/src/providers/poeditor.provider.ts:25-41
- Transifex: Uses asynchronous resource uploads for handling large translation sets and supports organization-level scoping. Sources: packages/translations/src/providers/transifex.provider.ts:65-128
- SimpleLocalize: Features native integration for auto-translation jobs and rate-limit handling with retries. Sources: packages/translations/src/providers/simplelocalize.provider.ts:245-316
Workflow Lifecycle
The typical workflow involves extracting local changes, pushing them to the provider for translation, and pulling the results back into the repository.
This diagram represents the interaction between the developer, the Nx toolkit, and external APIs during a standard translation cycle.
Sources: packages/translations/README.md:57-77, e2e/translations-e2e/tests/translations.spec.ts:89-98
Machine Translation
The translate executor enables automatic translation using services like DeepL. It checks for missing strings in target languages and populates them using the configured translator. For DeepL, options like formality (e.g., "less") can be specified in translatorOptions.
Sources: packages/translations/README.md:46-50, packages/translations/src/providers/simplelocalize.provider.ts:245-265
Setup and Installation
You can add the plugin to a project using the add generator.
- Run
npm install -D @nx-extend/translations. - Execute
nx g @nx-extend/translations:add <project-name>.
The generator creates a default .translationsrc.json in the project root and appends @nx-extend/translations/plugin to the plugins array in nx.json.
Sources: packages/translations/README.md:16-19, packages/translations/src/generators/add/add.impl.ts:77-96