From fef7892821db31d633f799ebcd91c63073bce196 Mon Sep 17 00:00:00 2001 From: Ken Sternberg Date: Tue, 9 Jan 2024 14:14:25 -0800 Subject: [PATCH] web: localization This package contains all the localization strings needed by all of the other packages in our application, and provides tooling for making them available as JavaScript translation catalogs suitable for `lit-localize`. It does this by scanning the source trees of all of the packages and assembling the complete list of translatable (and already translated) strings into the `./xliff` folder. Commands provided: - extract-locales: extracts any string tagged as translatable (i.e., with the `msg(...)` syntax) and integrates any newfound strings into the existing XLIFF files. Also: reprocesses the `sourceLocale` file to create a pseudolocale for testing purposes. (This must be done sequentially, as the `sourceLocale` file must be built before the conversion takes place.) - build: Convert XLIFF to Typescript, compile, lint, and format. The `lint` pass is especially important as it enforces the "backquotes to doublequotes when no template in use" rule, and the `format` pass must always come last to ensure our committed code matches our standard. - clean: Delete the `dist` and `src` folders, as well as the constructed `.mjs` file for pseudolocalization. Due to the circular nature of translation's dependencies (*every* package must be scanned for new strings, and if there are new strings, *every* package must then be rebuilt), extraction is not performed automatically. This introduces the risk that a developer may not run the extraction and test as needed. The reminder in the GitHub pull request template is there for a reason. If you add a new package to the monorepo and it has strings that need translating, you must add it to the list of `inputFiles` scanned in `lit-localize.json`. --- (p.s.: The content you just read is also in the README file for this package.) --- web/lage.config.js | 1 + web/package.json | 1 + web/packages/localization/README.md | 33 ++++++++++++++++++++++++++ web/packages/localization/package.json | 2 +- 4 files changed, 36 insertions(+), 1 deletion(-) create mode 100644 web/packages/localization/README.md diff --git a/web/lage.config.js b/web/lage.config.js index 87205c147..d77249f0d 100644 --- a/web/lage.config.js +++ b/web/lage.config.js @@ -2,6 +2,7 @@ module.exports = { pipeline: { "extract-locales": [], "build-locales": [], + "clean": [], "build-locales:build": [], "build-locales:repair": [], "rollup:build": [], diff --git a/web/package.json b/web/package.json index 816c9cc63..fc4324129 100644 --- a/web/package.json +++ b/web/package.json @@ -8,6 +8,7 @@ "build-locales": "lage build-locales", "build-locales:build": "lage build-locales:build", "build-locales:repair": "lage build-locales:repair", + "clean": "lage clean", "rollup:build": "lage rollup:build", "rollup:build-proxy": "lage rollup:build-proxy", "rollup:watch": "lage rollup:watch", diff --git a/web/packages/localization/README.md b/web/packages/localization/README.md new file mode 100644 index 000000000..17d6804b6 --- /dev/null +++ b/web/packages/localization/README.md @@ -0,0 +1,33 @@ +web: localization + +This package contains all the localization strings needed by all of the other packages in our +application, and provides tooling for making them available as JavaScript translation catalogs +suitable for `lit-localize`. It does this by scanning the source trees of all of the packages and +assembling the complete list of translatable (and already translated) strings into the `./xliff` +folder. + +Commands provided: + +- extract-locales: extracts any string tagged as translatable (i.e., with the `msg(...)` syntax) and + integrates any newfound strings into the existing XLIFF files. Also: reprocesses the + `sourceLocale` file to create a pseudolocale for testing purposes. (This must be done + sequentially, as the `sourceLocale` file must be built before the conversion takes place.) +- build: Convert XLIFF to Typescript, compile, lint, and format. The `lint` pass is especially + important as it enforces the "backquotes to doublequotes when no template in use" rule, and the + `format` pass must always come last to ensure our committed code matches our standard. +- clean: Delete the `dist` and `src` folders, as well as the constructed `.mjs` file for + pseudolocalization. + +## User notes: + +Due to the circular nature of translation's dependencies (*every* package must be scanned for new +strings, and if there are new strings, *every* package must then be rebuilt), extraction is not +performed automatically. This introduces the risk that a developer may not run the extraction and +test as needed. The reminder in the GitHub pull request template is there for a reason. + +## Maintenance note: + +If you add a new package to the monorepo and it has strings that need translating, you must add it +to the list of `inputFiles` scanned in `lit-localize.json`. + + diff --git a/web/packages/localization/package.json b/web/packages/localization/package.json index ca2165e04..ecf101da0 100644 --- a/web/packages/localization/package.json +++ b/web/packages/localization/package.json @@ -12,7 +12,7 @@ "clean:dist": "rimraf dist scripts/*.mjs", "clean:build": "rimraf src", "clean": "npm-run-all --parallel clean:dist clean:build", - "extract-locales": "run-p localization:extract localization:pseudolocalize", + "extract-locales": "npm-run-all --sequential localization:extract localization:pseudolocalize", "lint:lint": "eslint . --max-warnings 0", "fix:lint": "eslint . --max-warnings 0 --fix dist/locale-codes.js", "fix:prettier": "prettier --write ./src/**/* ./package.json ./lit-localize.json",