Skip to content

Latest commit

 

History

History
97 lines (62 loc) · 7.79 KB

localization.md

File metadata and controls

97 lines (62 loc) · 7.79 KB

Localization Resources and Crowdin Configuration

English | 简体中文

Crowdin is the translation management service. The host maintains its own language resources; external plugins build and maintain translations in their independent repository.

Backend Maven builds download translations from Crowdin during generate-resources, writing apps/backend/crydaq-server/src/main/resources/lang/messages_*.properties before copying resources into the JAR. pnpm build:backend, complete builds, development backend startup, and desktop packaging all pass through this phase. Git ignores all locale files in this Crowdin bundle family. The default English source messages.properties, the supplemental bundles (math-errors, rt60-errors, sound-power-errors, and can-errors), and frontend language resources remain tracked.

The existing Maven property skip.crowdin.download controls downloads and defaults to false:

# Download by default, then build the backend
pnpm build:backend
# Work offline or use only local language resources
pnpm build:backend "-Dskip.crowdin.download=true"
# Alternatively, invoke Maven directly from apps/backend
mvn package "-Dskip.crowdin.download=true"
# Explicitly enable downloads, matching the default
mvn package "-Dskip.crowdin.download=false"

In PowerShell, quote the entire dotted -D argument so it is not split into separate arguments.

Default downloads require an installed Crowdin CLI, valid configuration, and network access. A failed download stops the build to avoid delivering outdated translations. true skips the entire Maven download step and requires neither the CLI nor credentials. When a build skips downloads in a fresh checkout, the backend uses the tracked supplemental bundles and falls back to English in messages.properties for untranslated keys in the Crowdin bundle.

Complete desktop packaging also downloads by default. Keep downloads enabled for release packages that must include Crowdin translations. The community installer jobs (including daily, release candidate, and stable builds) explicitly skip downloads. The backend test workflow does not set the skip flag and follows Maven's default. To skip downloads locally, pass -Dskip.crowdin.download=true through Maven's standard MAVEN_ARGS environment variable while preserving existing Maven arguments.

Maintainer Local Configuration

Keep real project IDs, tokens, and Crowdin configuration only under Git-ignored .local/crowdin/, outside application source and resource directories. The repository supplies a backend example containing only environment-variable names and language-file mappings.

For initial setup, run at the host repository root. Do not overwrite existing local configuration:

New-Item -ItemType Directory -Force .local/crowdin
Copy-Item tools/crowdin/backend.example.yml .local/crowdin/backend.yml

Provide CROWDIN_PROJECT_ID and CROWDIN_API_TOKEN in the current terminal or maintainer build environment. Do not put real values into scripts, documentation, command examples, or commits. Configuration reads them through the example's environment-variable fields.

Maintainers install the Crowdin CLI themselves; builds do not install it. Windows defaults to crowdin.cmd; Mac/Linux default to crowdin. Builds read .local/crowdin/backend.yml. Override through -Dcrowdin.config=<absolute-path> and -Dcrowdin.executable=<CLI-path>. Automated builds also need the CLI and credentials, or an explicit download-skip argument.

Manual synchronization remains available:

crowdin upload sources --config .local/crowdin/backend.yml
crowdin download --config .local/crowdin/backend.yml

Only explicit commands upload content. Backend builds invoke download and never upload source text. Review generated translations in Crowdin; use a normal Git review for changes to the default English source or supplemental bundles.

The example uses Crowdin's supported project_id_env and api_token_env fields. base_path resolves relative to the configuration file, so first copy the example to the local directory above. See CLI Configuration and Path Rules.

Manual Host Upload and Download

The host continues to update the original Crowdin files client-en.js and messages.properties. This tool synchronizes only host frontend and backend translations, excluding independent cloud-service language resources.

Generate an offline snapshot at the repository root:

node tools/crowdin-host.mjs prepare --scope frontend
node tools/crowdin-host.mjs prepare --scope backend

The command prints its snapshot directory. For the frontend, it merges the English entry point and supplemental modules into plain text under the original filename client-en.js; it does not upload an incomplete entry point with module dependencies. Backend properties are preserved. Snapshot configuration contains only credential environment-variable names, without real values.

Replace SNAPSHOT below with the printed absolute directory. This snapshot tool accesses Crowdin only for explicit upload or download:

node tools/crowdin-host.mjs check --snapshot SNAPSHOT
node tools/crowdin-host.mjs upload --snapshot SNAPSHOT
node tools/crowdin-host.mjs download --snapshot SNAPSHOT

Run prepare again whenever original files or their frontend dependencies change. Downloads write only to the snapshot's translations directory, without overwriting the working tree. Review text, parameters, and language codes against existing files, then merge manually and run the relevant language tests. The tool does not automatically apply host translations.

External plugins build independently in OpenTest-Plugins. See Plugin Translation Builds and Maintenance. Plugin builds can skip downloading with pnpm build <plugin> "-Dskip.crowdin.download=true"; credentials come from plugin environment variables or ignored .local/crowdin.env. Default host builds and packaging do not prepare external plugins. Explicit --plugins-dir accepts existing packages; host packaging's MAVEN_ARGS affects only backend builds actually executed in that process.

Each plugin's frontend and backend share its packaged language resources. The default language defines valid keys. Parameterized-message type contracts are declared only in the plugin manifest's localization.parameters; ordinary names are not registered twice, and message-keys.json is no longer delivered.

When human translation is incomplete, runtime falls back to the default language. Set -Dskip.crowdin.download=true explicitly to use only valid local translations.

Commit and Packaging Boundaries

  • Root .gitignore excludes .crowdin.yml, .crowdin.yaml, crowdin.yml, and crowdin.yaml throughout frontend, backend, and all subdirectories. Actual configuration with other names must also reside under .local/.
  • Backend resource copying and JAR packaging exclude those four configuration names, including stale files in target/classes. Language files are still packaged.
  • Ignore rules do not modify committed history or existing installers. After configuration changes, rebuild the artifacts to be delivered.

Targeted regression commands require Git, a JDK, and Maven, using the developer's Maven settings:

node --test tools/__tests__/localization-packaging.test.mjs
node --test tools/__tests__/backend-crowdin.test.mjs

These tests use isolated directories to check Git ignore rules, Maven download arguments, download-failure handling, configuration exclusion, and packaged translations. Downloads use a command-line test double without connecting to Crowdin or modifying running application artifacts.