Merge pull request #32904 from backstage/rugvip/translation-export-import

cli: add translations export and import commands
2026-02-23 13:18:03 +01:00
parent e75d80dbc5 1dfc3436d9
commit ce676fea2f
14 changed files with 1372 additions and 16 deletions
@@ -24,6 +24,7 @@ repo [command]                                 Command that run across an entire
 package [command]                              Lifecycle scripts for individual packages
 migrate [command]                              Migration utilities
 versions:bump [options]                        Bump Backstage packages to the latest versions
+translations [command]                         Translation message management
 clean                                          Delete cache directories [DEPRECATED]
 build-workspace <workspace-dir> [packages...]  Builds a temporary dist workspace from the provided
                                                packages
@@ -429,6 +430,73 @@ YAML file that can be referenced in the GitHub integration configuration.
 Usage: backstage-cli create-github-app <github-org>
 ```

+## translations export
+
+Export translation messages from an app and all of its frontend plugins to JSON
+files. This command must be run from within a package directory (e.g.
+`packages/app`), not from the repository root.
+
+The command discovers all `TranslationRef` definitions in the dependency tree,
+extracts their default messages using the TypeScript type system, and writes
+them as JSON files along with a manifest.
+
+For more details on the translation workflow, see the
+[Internationalization](../../plugins/internationalization.md) documentation.
+
+```text
+Usage: backstage-cli translations export [options]
+
+Options:
+  --output <dir>       Output directory for exported messages and manifest (default: "translations")
+  --pattern <pattern>  File path pattern for message files relative to the output
+                       directory, with {id} and {lang} placeholders
+                       (default: "messages/{id}.{lang}.json")
+  -h, --help           display help for command
+```
+
+### Examples
+
+Export translations with default settings:
+
+```bash
+cd packages/app
+yarn backstage-cli translations export
+```
+
+Export with language-based directory grouping:
+
+```bash
+yarn backstage-cli translations export --pattern '{lang}/{id}.json'
+```
+
+## translations import
+
+Generate translation resource wiring code from translated JSON files. Reads the
+manifest and translated message files produced by `translations export`, and
+generates a TypeScript module that creates `TranslationResource` objects for each
+translated ref.
+
+The file pattern used during export is stored in the manifest and automatically
+used by the import command.
+
+```text
+Usage: backstage-cli translations import [options]
+
+Options:
+  --input <dir>    Input directory containing the manifest and translated message files (default: "translations")
+  --output <path>  Output path for the generated wiring module (default: "src/translations/resources.ts")
+  -h, --help       display help for command
+```
+
+### Examples
+
+Generate wiring code with default settings:
+
+```bash
+cd packages/app
+yarn backstage-cli translations import
+```
+
 ## info

 Outputs debug information which is useful when opening an issue. Outputs system