Skip to content

Latest commit

 

History

History
115 lines (74 loc) · 7.97 KB

localization.md

File metadata and controls

115 lines (74 loc) · 7.97 KB

Plugin Translation Builds and Maintenance

English | 简体中文

Run the following commands in the independent OpenTest-Plugins repository. Each plugin maintains English source and target-language JSON, shared by its frontend and Java backend. Before compilation, plugin builds download selected translations from Crowdin, the translation management service, then validate and apply name keys, parameters, and language mappings before checks, compilation, and packaging. Entries not translated remotely retain valid local translations and default-language fallback.

Downloads During Builds

# Download by default, then perform the complete build
pnpm build fft-tools
pnpm build:signed fft-tools --platform windows
# Skip downloads using the same argument as the host backend
pnpm build fft-tools "-Dskip.crowdin.download=true"
# Explicitly enable downloads, matching the default
pnpm build fft-tools "-Dskip.crowdin.download=false"
# Synchronize only selected plugins, validate and apply; do not compile or upload
node tools/crowdin.mjs sync fft-tools

In PowerShell, quote the entire dotted -D argument.

Single-side plugin builds also synchronize by default. Repackaging through package or package:signed uses existing resources without downloading again. The host builds and packages independently by default. Explicit --plugins-dir accepts existing plugin packages without triggering downloads. Independent plugin builds use their own skip arguments; host packaging's MAVEN_ARGS affects only backend builds actually executed in that process.

Install the Crowdin CLI yourself and configure CROWDIN_PROJECT_ID and CROWDIN_API_TOKEN through environment variables or Git-ignored .local/crowdin.env. Environment variables take priority. Tools do not install software or upload source text. Download, authentication, network, or translation-validation failures stop compilation. Plugins or languages absent remotely are reported as missing translations while local resources are retained. Offline builds without credentials must explicitly skip downloads.

Build downloads reuse the snapshot and import procedures below, preparing only selected plugins without replacing English source or other plugins. Snapshots and reports reside in .runtime/crowdin/. Review downloaded language-resource changes through the normal process.

Translation changes also change plugin content, so releases must follow plugin version-increment rules. Downloads and builds do not automatically change the version in plugin.json.

Preparing a Plugin

Run at the plugin repository root:

pnpm crowdin:check -- --plugin fft-tools
pnpm crowdin:prepare -- --plugin fft-tools

To prepare all plugins, replace --plugin fft-tools with --all. Output contains a snapshot, source-text copies, Crowdin configuration, and missing-translation reports. The default output is Git-ignored .runtime/crowdin/. Use --output <nonexistent-directory> to choose another location.

Crowdin file mappings use plugins/<plugin-directory>.json, distinguishing files by plugin name. Source copies come from each plugin's default-language resources. Local language filenames remain names such as en-US.json. Generated configuration contains only selected plugins' language resources, excluding host and independent cloud-service language resources and license text. Snapshots retain text and manifest digests; subsequent synchronization requires preparation again if those inputs change.

For FFT, upload, download, and import paths correspond as follows:

Purpose Path
Local English source plugins/fft-tools/frontend/locales/en-US.json
Prepared source copy sources/plugins/fft-tools/en-US.json
Crowdin file plugins/fft-tools.json
Download staging, relative to the reported translations directory fft-tools/zh-CN.json
Validated import destination plugins/fft-tools/frontend/locales/zh-CN.json

Move and rename the old remote plugins/<plugin-directory>/en-US.json to the path above while preserving its file ID; do not delete and upload it again. Remove only confirmed-empty old plugin directories. Run prepare again and use its new configuration for upload or download instead of reusing an old prepared crowdin.yml.

Uploading Source Text

Install the Crowdin CLI, set CROWDIN_PROJECT_ID and CROWDIN_API_TOKEN in the terminal or .local/crowdin.env, then use the snapshot path printed by prepare:

pnpm crowdin:upload -- --snapshot <prepared-directory>/snapshot.json

The command uploads source text without translating or automatically approving translations. Changed source text retains existing translations, which then need human confirmation again. Environment-variable fields, remote paths, and language mappings follow Crowdin Configuration. Do not place real credentials in generated configuration or commits.

You can also create the corresponding plugin directory in the Crowdin web interface and upload the prepared JSON manually. The host continues to use client-en.js and messages.properties; this tool does not update them.

Downloading and Reviewing Translations

After remote translation is ready, run:

pnpm crowdin:download -- --snapshot <prepared-directory>/snapshot.json

This manual command writes to a new staging directory, validates name keys, parameters, and language mappings, and reports differences and missing translations without directly changing plugin resources. Build-time sync automatically applies translations after the same validation. Pass -Dskip.crowdin.download=true to build locally without downloads.

When no translations can be exported remotely, the result lists the relevant plugins as skipped and preserves existing local language files.

After reviewing differences, use the translations directory printed by download:

pnpm crowdin:import -- --snapshot <prepared-directory>/snapshot.json --from <translations-directory>
pnpm crowdin:import -- --snapshot <prepared-directory>/snapshot.json --from <translations-directory> --apply

The first command only checks. The second applies changes after all inputs pass validation. Empty or undownloaded entries do not clear existing translations, and undownloaded languages stay unchanged. Downloaded content cannot replace English source, introduce unknown names, or modify unselected plugins. Local translation edits made since preparation also block overwrites. Review the Git diff after applying changes, then commit normally.

Importing Files Downloaded from the Website

When exporting from the website, skip untranslated entries so English fallback is not mistaken for finished translation. Extract the ZIP outside the tool, arrange it as below, then use the same import command:

translations/
  fft-tools/
    zh-CN.json
    ja-JP.json

Language filenames must match locales declared in the plugin manifest. The tool rejects unknown languages and symbolic links. Directories for unselected plugins are ignored. Do not copy a ZIP directly over the working tree.

Reusing Existing Translations

When reusing translations, first convert files according to the plugin's actual name keys. Identical English text or prefixes do not replace explicit ownership mappings. Validate each language file with import, then manually import those translations into the corresponding Crowdin plugin file and reconfirm their meaning and parameters.

Message parameter types are maintained only in the plugin manifest's sparse parameters declarations and are not uploaded for translation. Default-language resources define valid names; there is no separate message index.

Tool Verification

node --test tools/test/crowdin.test.mjs

Tests use local snapshots and simulated downloads to check selection scope, missing-translation reports, previews and application, stale-input rejection, and parameter validation. They do not connect to Crowdin or demonstrate that remote import is complete.