Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

feat(i18n): add check, report, and schema maintenance scripts

Tinc2204ab2e643
diff --git a/package.json b/package.json
index a57fdf7d1..78ba298e3 100644
--- a/package.json
+++ b/package.json
@@ -5,6 +5,11 @@
"scripts": {
"build": "turbo build",
"dev": "turbo dev",
+ "i18n:check": "node ./scripts/i18n/check.mjs",
+ "i18n:check:fix": "node ./scripts/i18n/check.mjs --fix",
+ "i18n:report": "node ./scripts/i18n/report.mjs",
+ "i18n:report:fix": "node ./scripts/i18n/report.mjs --fix",
+ "i18n:schema": "node ./scripts/i18n/schema.mjs",
"lint": "turbo lint",
"prepare": "husky"
},
diff --git a/scripts/i18n/check.mjs b/scripts/i18n/check.mjs
new file mode 100644
index 000000000..c8aa820d2
--- /dev/null
+++ b/scripts/i18n/check.mjs
@@ -0,0 +1,70 @@
+import {
+ defaultLocale,
+ flattenLocale,
+ formatKeyList,
+ getValueAtKey,
+ loadLocales,
+ setValueAtKey,
+ writeJson,
+} from "./shared.mjs";
+
+const args = process.argv.slice(2);
+const shouldFix = args.includes("--fix");
+const localeFilter = args.find((arg) => arg !== "--fix");
+
+const { locales, reference } = await loadLocales();
+const referenceKeys = flattenLocale(reference.data);
+const targetLocales = locales.filter(({ locale }) => locale !== defaultLocale);
+const filteredLocales = localeFilter
+ ? targetLocales.filter(({ locale }) => locale === localeFilter)
+ : targetLocales;
+
+if (localeFilter && filteredLocales.length === 0) {
+ console.error(`No locale found for "${localeFilter}".`);
+ process.exit(1);
+}
+
+let hasIssues = false;
+
+for (const locale of filteredLocales) {
+ const localeKeys = flattenLocale(locale.data);
+ const missing = new Set([...referenceKeys].filter((key) => !localeKeys.has(key)));
+ const extra = new Set([...localeKeys].filter((key) => !referenceKeys.has(key)));
+
+ if (missing.size === 0 && extra.size === 0) {
+ console.log(`${locale.locale}: OK`);
+ continue;
+ }
+
+ hasIssues = true;
+ console.log(`${locale.locale}:`);
+
+ if (missing.size > 0) {
+ console.log(" Missing keys:");
+ for (const key of formatKeyList(missing)) {
+ console.log(` - ${key}`);
+ if (shouldFix) {
+ setValueAtKey(locale.data, key, getValueAtKey(reference.data, key));
+ }
+ }
+ }
+
+ if (extra.size > 0) {
+ console.log(" Extra keys:");
+ for (const key of formatKeyList(extra)) {
+ console.log(` - ${key}`);
+ }
+ }
+
+ if (shouldFix && missing.size > 0) {
+ await writeJson(locale.path, locale.data);
+ console.log(" Added missing keys from en-US.");
+ }
+}
+
+if (!hasIssues) {
+ console.log("All locale files are in sync with en-US.");
+ process.exit(0);
+}
+
+process.exit(shouldFix ? 0 : 1);
diff --git a/scripts/i18n/report.mjs b/scripts/i18n/report.mjs
new file mode 100644
index 000000000..1217fade6
--- /dev/null
+++ b/scripts/i18n/report.mjs
@@ -0,0 +1,144 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+ defaultLocale,
+ flattenLocale,
+ formatKeyList,
+ loadLocales,
+ pruneLocale,
+ repoRoot,
+ writeJson,
+} from "./shared.mjs";
+
+const pluralForms = ["_zero", "_one", "_two", "_few", "_many", "_other"];
+
+const args = process.argv.slice(2);
+const shouldFix = args.includes("--fix");
+
+const { locales, reference } = await loadLocales();
+const localeKeys = flattenLocale(reference.data);
+const sourceFiles = await collectSourceFiles(path.join(repoRoot, "apps", "web", "src"));
+const { staticKeys, dynamicCalls, dynamicPrefixes } = await collectUsedKeys(sourceFiles);
+
+const missing = new Set(
+ [...staticKeys].filter((key) => !isRepresentedByLocaleKeys(key, localeKeys)),
+);
+const unused = new Set(
+ [...localeKeys].filter(
+ (key) =>
+ !isLocaleKeyUsed(key, staticKeys) &&
+ !dynamicPrefixes.some((prefix) => key.startsWith(prefix)),
+ ),
+);
+
+if (missing.size === 0 && unused.size === 0 && dynamicCalls.length === 0) {
+ console.log("i18n report is clean.");
+} else {
+ if (missing.size > 0) {
+ console.log("Missing keys:");
+ for (const key of formatKeyList(missing)) {
+ console.log(` - ${key}`);
+ }
+ }
+
+ if (unused.size > 0) {
+ console.log("Unused keys:");
+ for (const key of formatKeyList(unused)) {
+ console.log(` - ${key}`);
+ }
+ }
+
+ if (dynamicCalls.length > 0) {
+ console.log("Dynamic keys:");
+ for (const call of dynamicCalls) {
+ console.log(` - ${call}`);
+ }
+ }
+}
+
+if (shouldFix) {
+ if (unused.size === 0) {
+ console.log("No unused keys to remove.");
+ } else {
+ const allowedKeys = new Set([...localeKeys].filter((key) => !unused.has(key)));
+
+ for (const locale of locales) {
+ const nextLocale = pruneLocale(locale.data, allowedKeys);
+ await writeJson(locale.path, nextLocale);
+ }
+
+ console.log(`Removed ${unused.size} unused key(s) from ${defaultLocale} and other locales.`);
+ }
+}
+
+if (missing.size > 0 || dynamicCalls.length > 0) {
+ process.exit(1);
+}
+
+process.exit(0);
+
+async function collectSourceFiles(rootDir) {
+ const entries = await fs.readdir(rootDir, { withFileTypes: true });
+ const files = await Promise.all(
+ entries.map(async (entry) => {
+ const fullPath = path.join(rootDir, entry.name);
+ if (entry.isDirectory()) {
+ return collectSourceFiles(fullPath);
+ }
+
+ if (!/\.(ts|tsx)$/u.test(entry.name)) {
+ return [];
+ }
+
+ return [fullPath];
+ }),
+ );
+
+ return files.flat();
+}
+
+async function collectUsedKeys(files) {
+ const staticKeys = new Set();
+ const dynamicCalls = [];
+ const dynamicPrefixes = [];
+
+ for (const file of files) {
+ const source = await fs.readFile(file, "utf8");
+
+ for (const match of source.matchAll(/\b(?:[\w$]+\.)?t\(\s*(['"])([^'"\\]+)\1/gu)) {
+ staticKeys.add(match[2]);
+ }
+
+ for (const match of source.matchAll(/\bi18nKey\s*=\s*(['"])([^'"\\]+)\1/gu)) {
+ staticKeys.add(match[2]);
+ }
+
+ for (const match of source.matchAll(/\b(?:[\w$]+\.)?t\(\s*(`[^`]*\$\{[^`]*\}`|[^'"`\s][^,\n)]*)/gu)) {
+ const call = match[0].trim();
+ dynamicCalls.push(`${path.relative(repoRoot, file)}: ${call}`);
+ const prefixMatch = call.match(/`([^`$]*)\$\{/u);
+ if (prefixMatch?.[1]) {
+ dynamicPrefixes.push(prefixMatch[1]);
+ }
+ }
+ }
+
+ return { staticKeys, dynamicCalls, dynamicPrefixes };
+}
+
+function isRepresentedByLocaleKeys(key, localeKeys) {
+ if (localeKeys.has(key)) {
+ return true;
+ }
+
+ return pluralForms.some((suffix) => localeKeys.has(`${key}${suffix}`));
+}
+
+function isLocaleKeyUsed(key, staticKeys) {
+ if (staticKeys.has(key)) {
+ return true;
+ }
+
+ const baseKey = key.replace(/_(zero|one|two|few|many|other)$/u, "");
+ return baseKey !== key && staticKeys.has(baseKey);
+}
diff --git a/scripts/i18n/schema.mjs b/scripts/i18n/schema.mjs
new file mode 100644
index 000000000..7d446db0e
--- /dev/null
+++ b/scripts/i18n/schema.mjs
@@ -0,0 +1,35 @@
+import { loadLocales, schemaPath, writeJson } from "./shared.mjs";
+
+const { reference } = await loadLocales();
+
+const schema = {
+ $schema: "https://json-schema.org/draft/2020-12/schema",
+ $id: "https://kaneo.app/i18n/schema.json",
+ title: "Kaneo locale schema",
+ type: "object",
+ additionalProperties: false,
+ properties: buildProperties(reference.data),
+ required: Object.keys(reference.data),
+};
+
+await writeJson(schemaPath, schema);
+console.log(`Wrote ${schemaPath}`);
+
+function buildProperties(value) {
+ return Object.fromEntries(
+ Object.entries(value).map(([key, child]) => [key, buildSchemaNode(child)]),
+ );
+}
+
+function buildSchemaNode(value) {
+ if (typeof value === "string") {
+ return { type: "string" };
+ }
+
+ return {
+ type: "object",
+ additionalProperties: false,
+ properties: buildProperties(value),
+ required: Object.keys(value),
+ };
+}
diff --git a/scripts/i18n/shared.mjs b/scripts/i18n/shared.mjs
new file mode 100644
index 000000000..30510dcb7
--- /dev/null
+++ b/scripts/i18n/shared.mjs
@@ -0,0 +1,151 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const repoRoot = path.resolve(__dirname, "../..");
+export const i18nDir = path.join(repoRoot, "i18n");
+export const defaultLocale = "en-US";
+export const schemaPath = path.join(i18nDir, "schema.json");
+
+export async function getLocaleFiles() {
+ const entries = await fs.readdir(i18nDir, { withFileTypes: true });
+
+ return entries
+ .filter(
+ (entry) =>
+ entry.isFile() &&
+ entry.name.endsWith(".json") &&
+ entry.name !== path.basename(schemaPath),
+ )
+ .map((entry) => ({
+ locale: entry.name.replace(/\.json$/u, ""),
+ path: path.join(i18nDir, entry.name),
+ }))
+ .sort((a, b) => a.locale.localeCompare(b.locale));
+}
+
+export async function readJson(filePath) {
+ return JSON.parse(await fs.readFile(filePath, "utf8"));
+}
+
+export async function writeJson(filePath, value) {
+ await fs.writeFile(filePath, `${JSON.stringify(value, null, "\t")}\n`);
+}
+
+export async function loadLocales() {
+ const localeFiles = await getLocaleFiles();
+ const locales = await Promise.all(
+ localeFiles.map(async ({ locale, path: filePath }) => ({
+ locale,
+ path: filePath,
+ data: await readJson(filePath),
+ })),
+ );
+
+ const reference = locales.find(({ locale }) => locale === defaultLocale);
+
+ if (!reference) {
+ throw new Error(`Missing reference locale: ${defaultLocale}.json`);
+ }
+
+ return { locales, reference };
+}
+
+export function flattenLocale(localeData) {
+ const keys = new Set();
+
+ for (const [namespace, value] of Object.entries(localeData)) {
+ collectKeys(value, `${namespace}:`, keys);
+ }
+
+ return keys;
+}
+
+function collectKeys(value, prefix, keys) {
+ if (typeof value === "string") {
+ keys.add(prefix.slice(0, -1));
+ return;
+ }
+
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
+ keys.add(prefix.slice(0, -1));
+ return;
+ }
+
+ for (const [childKey, childValue] of Object.entries(value)) {
+ collectKeys(childValue, `${prefix}${childKey}.`, keys);
+ }
+}
+
+export function getValueAtKey(localeData, translationKey) {
+ const [namespace, nestedPath] = translationKey.split(":");
+ const segments = nestedPath.split(".");
+ let current = localeData[namespace];
+
+ for (const segment of segments) {
+ current = current?.[segment];
+ }
+
+ return current;
+}
+
+export function setValueAtKey(localeData, translationKey, value) {
+ const [namespace, nestedPath] = translationKey.split(":");
+ const segments = nestedPath.split(".");
+ let current = localeData[namespace];
+
+ if (!current || typeof current !== "object" || Array.isArray(current)) {
+ current = {};
+ localeData[namespace] = current;
+ }
+
+ for (const segment of segments.slice(0, -1)) {
+ const next = current[segment];
+ if (!next || typeof next !== "object" || Array.isArray(next)) {
+ current[segment] = {};
+ }
+ current = current[segment];
+ }
+
+ current[segments.at(-1)] = value;
+}
+
+export function pruneLocale(localeData, allowedKeys) {
+ const nextLocale = {};
+
+ for (const [namespace, value] of Object.entries(localeData)) {
+ const nextValue = pruneNamespace(value, `${namespace}:`, allowedKeys);
+ if (nextValue !== undefined) {
+ nextLocale[namespace] = nextValue;
+ }
+ }
+
+ return nextLocale;
+}
+
+function pruneNamespace(value, prefix, allowedKeys) {
+ if (typeof value === "string") {
+ return allowedKeys.has(prefix.slice(0, -1)) ? value : undefined;
+ }
+
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
+ return allowedKeys.has(prefix.slice(0, -1)) ? value : undefined;
+ }
+
+ const nextValue = {};
+
+ for (const [childKey, childValue] of Object.entries(value)) {
+ const pruned = pruneNamespace(childValue, `${prefix}${childKey}.`, allowedKeys);
+ if (pruned !== undefined) {
+ nextValue[childKey] = pruned;
+ }
+ }
+
+ return Object.keys(nextValue).length > 0 ? nextValue : undefined;
+}
+
+export function formatKeyList(keys) {
+ return [...keys].sort((a, b) => a.localeCompare(b));
+}