diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 522e298..4ef2323 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,7 +18,7 @@ If you use an AI assistant, point it at `AGENTS.md`; the `adev-translation` skil - `tools/` is plain Node (ESM, no build step): one [citty](https://github.com/unjs/citty) CLI (`tools/cli.mjs`) whose subcommands live in `tools/commands/`, shared code in `tools/lib/`. Prefer a maintained library over custom code (see [docs/architecture.md](docs/architecture.md#tooling)). Every subcommand has a `pnpm ` alias of the same name in `package.json`; a name that pnpm itself owns (`setup`, `deploy`, `init`, `docs`, `search`…) is unusable, because `pnpm ` runs pnpm's command instead of the script: `tools/test/scripts.test.mjs` rejects those. - Diagrams in `docs/` and the README are Mermaid blocks (GitHub renders them); keep them small, keep the commands in them identical to the real flags, and preview a change in GitHub's Markdown preview or at mermaid.live before opening the PR. -- `pnpm test` runs the suite in `tools/test/` (about a minute): one unit file per `tools/lib/` module, `scripts.test.mjs` for the `package.json` aliases, `cli.test.mjs` which drives the real CLI end to end in a temporary repository (scaffold, translate, check, sync, mechanical apply, dictionaries, glossary, report, Firebase config, `build --prepare-only`), and `parity.test.mjs` which runs upstream's own `heading.mts` against our anchor port. Tests never touch this checkout: they build throwaway repositories from `tools/test/fixtures/upstream` (a pocket `angular/angular`) and point the tooling at them with `ROSETTA_ROOT` / `ROSETTA_ORIGIN`. A change to a command needs a case in `cli.test.mjs`; a change to upstream's file layout needs the fixture updated. +- `pnpm test` runs the suite in `tools/test/` (about a minute): one unit file per `tools/lib/` module, `scripts.test.mjs` for the `package.json` aliases, `cli.test.mjs` which drives the real CLI end to end in a temporary repository (scaffold, translate, check, sync, mechanical apply, dictionaries, glossary, report, Firebase config, `build --prepare-only`), and `parity.test.mjs` which runs upstream's own `heading.mts` against our anchor port. Tests never touch this checkout, and never read its `i18n/` (repositories created from the template delete `i18n/_example`): they build throwaway repositories from `tools/test/fixtures/upstream` (a pocket `angular/angular`) and `tools/test/fixtures/example` (a frozen copy of the example's configuration) and point the tooling at them with `ROSETTA_ROOT` / `ROSETTA_ORIGIN`. A change to a command needs a case in `cli.test.mjs`; a change to upstream's file layout needs the fixture updated. - Never change files under `origin/`. Code-level changes to the site live in `tools/adev-patches/*.patch` and must pass `git apply --check` against the pinned upstream in CI. - Workflows pin actions by commit SHA. Keep permissions minimal. - Changes to skills or docs follow the same review as code. diff --git a/tools/lib/build-steps.mjs b/tools/lib/build-steps.mjs index 261ad95..c6923d9 100644 --- a/tools/lib/build-steps.mjs +++ b/tools/lib/build-steps.mjs @@ -2,7 +2,7 @@ * Steps shared by `pnpm build` and `pnpm start`: worktree, patches, overlay, dictionaries, * status report, pnpm in the build directory, post-processing of the output. */ -import {appendFile, readFile} from 'node:fs/promises'; +import {appendFile, chmod, copyFile as fsCopyFile, cp, lstat, readFile, readdir, realpath, stat, unlink} from 'node:fs/promises'; import path from 'node:path'; import {applyIndexHtmlPairs, applyNavLabels, applyPipelinePairs, applyTemplateStrings} from './adev.mjs'; import {git, run} from './exec.mjs'; @@ -253,12 +253,51 @@ export async function checkNodeVersion(dir) { export const OUTPUT_REL = path.join('dist', 'bin', 'adev', 'dist', 'browser'); +/** + * Bazel writes its outputs read-only (files 0444, directories 0555), and parts of the output tree + * (assets/content, for example) are symlinks into other read-only Bazel outputs. Post-processing + * edits the tree in place, so: replace every symlink with a real copy of its target (Bazel's own + * outputs stay untouched), then give the owner write access to every file and directory. + * Dangling symlinks are left as they are. + */ +export async function makeWritable(dir) { + let count = 0; + const walk = async (p) => { + let st = await lstat(p); + if (st.isSymbolicLink()) { + let target; + try { + target = await realpath(p); + } catch { + return; + } + const tst = await stat(target); + await unlink(p); + if (tst.isDirectory()) await cp(target, p, {recursive: true, dereference: true}); + else await fsCopyFile(target, p); + count++; + st = await lstat(p); + } + const mode = st.mode & 0o7777; + const want = st.isDirectory() ? mode | 0o700 : mode | 0o200; + if (want !== mode) { + await chmod(p, want); + count++; + } + if (st.isDirectory()) for (const name of await readdir(p)) await walk(path.join(p, name)); + }; + await walk(dir); + return count; +} + /** Rewrite edit links, add canonical + hreflang per page, write sitemap.xml and robots.txt. */ export async function postProcess(lang, dir) { const site = await loadSite(lang); const out = path.join(dir, OUTPUT_REL); if (!(await exists(out))) throw new Error(`build output not found at ${out}`); log.step('post-process output'); + const unlocked = await makeWritable(out); + if (unlocked) log.info(`made ${unlocked} read-only Bazel output entr${unlocked === 1 ? 'y' : 'ies'} writable`); const editFrom = ['https://github.com/angular/angular/edit/main/adev/src/content/', 'https://github.com/angular/angular/blob/main/adev/src/content/']; const editTo = `${site.repoUrl}/edit/${site.repo.branch}/i18n/${lang}/src/content/`; diff --git a/tools/test/build-steps.test.mjs b/tools/test/build-steps.test.mjs index bce4bf6..1cab1f7 100644 --- a/tools/test/build-steps.test.mjs +++ b/tools/test/build-steps.test.mjs @@ -4,6 +4,7 @@ * upstream as origin/ (a real git repository), so ROSETTA_ORIGIN stays unset like in a real build. */ import assert from 'node:assert/strict'; +import {chmod, lstat, mkdir, stat, symlink} from 'node:fs/promises'; import path from 'node:path'; import {after, before, describe, test} from 'node:test'; import {execa} from 'execa'; @@ -278,6 +279,47 @@ describe('postProcess', () => { await postProcess(lang, dir); assert.equal((await read(path.join(out, 'robots.txt'))).match(/Sitemap:/g).length, 1, 'idempotent'); }); + test('edits Bazel output even when files and directories are read-only', async () => { + const out = path.join(dir, OUTPUT_REL); + const page = path.join(out, 'ai/agent-skills/index.html'); + await write(page, 'Apage'); + await write(path.join(out, 'robots.txt'), 'User-agent: *\nAllow: /\n'); + await chmod(page, 0o444); + await chmod(path.join(out, 'robots.txt'), 0o444); + await chmod(path.join(out, 'ai/agent-skills'), 0o555); + await chmod(out, 0o555); + await postProcess(lang, dir); + assert.ok((await read(page)).includes('')); + assert.ok((await read(path.join(out, 'robots.txt'))).includes('Sitemap: https://angular.fr/sitemap.xml')); + // Root ignores permission bits, so also assert the modes themselves (CI runs as a normal user). + assert.equal((await stat(page)).mode & 0o200, 0o200, 'file made writable'); + assert.equal((await stat(path.join(out, 'ai/agent-skills'))).mode & 0o700, 0o700, 'directory made writable'); + }); + test('replaces symlinks into other Bazel outputs with writable copies, leaving the targets untouched', async () => { + const out = path.join(dir, OUTPUT_REL); + const elsewhere = path.join(dir, 'bazel-out-elsewhere'); + const target = path.join(elsewhere, 'content/ai/agent-skills.md.html'); + const blob = 'https://github.com/angular/angular/blob/main/adev/src/content/ai/agent-skills.md'; + await write(target, `

edit

`); + await write(path.join(elsewhere, 'single.js'), `const e = "${blob}";`); + await write(path.join(out, 'index.html'), 'home'); + await mkdir(path.join(out, 'assets'), {recursive: true}); + await symlink(path.join(elsewhere, 'content'), path.join(out, 'assets/content')); + await symlink(path.join(elsewhere, 'single.js'), path.join(out, 'single.js')); + await symlink(path.join(elsewhere, 'missing'), path.join(out, 'dangling')); + await chmod(target, 0o444); + await chmod(path.join(elsewhere, 'content/ai'), 0o555); + await postProcess(lang, dir); + const copied = path.join(out, 'assets/content/ai/agent-skills.md.html'); + assert.ok(!(await lstat(path.join(out, 'assets/content'))).isSymbolicLink(), 'directory symlink replaced by a copy'); + assert.ok(!(await lstat(path.join(out, 'single.js'))).isSymbolicLink(), 'file symlink replaced by a copy'); + assert.ok((await lstat(path.join(out, 'dangling'))).isSymbolicLink(), 'dangling symlink left alone'); + assert.equal((await stat(copied)).mode & 0o200, 0o200, 'copied file writable'); + assert.ok((await read(copied)).includes('https://github.com/org/docs-fr/edit/main/i18n/fr/src/content/ai/agent-skills.md')); + assert.ok((await read(target)).includes(blob), 'the Bazel output behind the symlink is not edited'); + assert.equal((await stat(target)).mode & 0o777, 0o444, 'and keeps its mode'); + await chmod(path.join(elsewhere, 'content/ai'), 0o755); // let the suite's cleanup remove it as a normal user + }); test('fails when there is no build output', async () => { await removeDir(path.join(dir, 'dist')); await assert.rejects(postProcess(lang, dir), /build output not found/); diff --git a/tools/test/fixtures/example/LANGUAGE.md b/tools/test/fixtures/example/LANGUAGE.md new file mode 100644 index 0000000..c28f26a --- /dev/null +++ b/tools/test/fixtures/example/LANGUAGE.md @@ -0,0 +1,60 @@ +--- +lang: fr +name: Français +direction: ltr +formality: formal +lineParity: strict +quotes: ["«", "»"] +spaceBeforePunctuation: + chars: [":", ";", "?", "!"] + space: " " +headingCase: sentence +numberFormat: "1 234,56" +dateFormat: "27 octobre 2026" +fonts: [] +--- + +# Règles de traduction : français + +Ces règles s'appliquent à toute page sous `i18n/fr/src/`. Le glossaire (`glossary.json`) fait foi pour la terminologie. En cas de doute, cherchez une page déjà traduite qui traite du même sujet et alignez-vous. + +## Registre et ton + +- Vouvoiement, toujours : « vous pouvez », jamais « tu peux ». +- Phrases directes, voix active quand l'anglais l'emploie. Ne rien ajouter : pas d'explication supplémentaire, pas d'avis, pas de promotion. +- Les instructions utilisent l'impératif à la deuxième personne du pluriel (« Créez un composant »), pas l'infinitif, sauf dans les listes de tâches courtes où l'anglais utilise des fragments. + +## Typographie + +- Espace fine insécable (U+202F) avant `:` `;` `?` `!`. Le vérificateur signale une espace ordinaire ou une absence d'espace. +- Guillemets français « » avec espaces insécables à l'intérieur. Les guillemets droits restent dans le code, les sorties de commande et les citations en anglais. +- Titres en casse de phrase : « Composants et modèles », pas « Composants Et Modèles ». +- Noms de produits et d'API tels quels : Angular, Angular CLI, TypeScript, `signal`, `computed`, `inject`. +- Nombres : espace insécable pour les milliers, virgule décimale (1 234,56). Dates en toutes lettres dans la prose (27 octobre 2026). + +## Ce qui reste en anglais + +- Les noms d'API, de fichiers, de commandes et d'options : `@Component`, `ng generate`, `--standalone`. +- Les termes marqués `keep` dans le glossaire : *signal*, *template*, *pipe*, *standalone*, *zoneless*, *hydration* est traduit (hydratation) mais *SSR* reste. +- Le code, y compris ses commentaires (règle v1), les exemples de sortie, les URL, les ancres. + +## Pièges + +- *Component* → composant (masculin). *Directive* → directive (féminin). *Signal* reste signal, masculin : un signal, des signals (pas « signaux », qui désigne le concept général). +- *Template* reste template (masculin : le template). Jamais « gabarit » ni « modèle ». +- *Dependency injection* → injection de dépendances (pluriel). *Change detection* → détection de changements. +- *Library* → bibliothèque, jamais « librairie ». +- *Form* → formulaire ; *reactive forms* → formulaires réactifs ; *signal forms* → formulaires à base de signals. +- *You* dans une instruction → « vous » ; *your application* → « votre application ». +- Ne traduisez pas les faux amis à l'identique : *actually* → en réalité ; *eventually* → au final ; *consistent* → cohérent. + +## Chaînes d'interface + +- Libellés de navigation et de boutons courts : nom ou infinitif, sans point final (« Guide », « Commencer », « Référence »). +- Respectez la longueur : un libellé de menu dépassant deux mots de plus que l'anglais déborde sur mobile. + +## Échantillon + +> **EN** Signals are Angular's primitive for reactive state. A signal holds a value and notifies interested consumers when that value changes. +> +> **FR** Les signals sont la primitive d'Angular pour l'état réactif. Un signal contient une valeur et notifie les consommateurs intéressés quand cette valeur change. diff --git a/tools/test/fixtures/example/README.md b/tools/test/fixtures/example/README.md new file mode 100644 index 0000000..58b12b1 --- /dev/null +++ b/tools/test/fixtures/example/README.md @@ -0,0 +1,24 @@ +# Français (exemple) — `i18n/_example` + +Reference language of the template. It carries a complete French `LANGUAGE.md`, a seeded glossary and generated dictionaries so the template's own CI can build a localized site. It is removed from repositories created from the template (`pnpm create-language` offers to delete it). + +Use it as a model for your own `i18n//README.md`: + +## Maintainers + +- `@handle` (lead), `@handle` + +## Where we talk + +- Chat: _link_ +- Issues: label `lang:fr` + +## How we review + +- New page: one translator, one reviewer who did not write the text. +- Outdated page (classes a, b, c): one reviewer. +- Terminology changes go through the glossary (`glossary.json`), not through line comments only. + +## Status + +- Coverage and freshness: `/assets/others/translation-status.json` on the site, or `pnpm report fr`. diff --git a/tools/test/fixtures/example/glossary.json b/tools/test/fixtures/example/glossary.json new file mode 100644 index 0000000..7cb2913 --- /dev/null +++ b/tools/test/fixtures/example/glossary.json @@ -0,0 +1,32 @@ +[ + {"term": "signal", "keep": true, "note": "API name; masculine in French: un signal, des signals", "forbidden": ["signaux"]}, + {"term": "template", "keep": true, "note": "masculine: le template", "forbidden": ["gabarit"]}, + {"term": "pipe", "keep": true, "note": "masculine: un pipe"}, + {"term": "standalone", "keep": true}, + {"term": "zoneless", "keep": true}, + {"term": "component", "translation": "composant", "note": "masculine"}, + {"term": "directive", "translation": "directive", "note": "feminine"}, + {"term": "service", "translation": "service"}, + {"term": "dependency injection", "translation": "injection de dépendances", "forbidden": ["injection de dépendance"]}, + {"term": "change detection", "translation": "détection de changements", "forbidden": ["détection des changements", "détection de changement"]}, + {"term": "hydration", "translation": "hydratation"}, + {"term": "server-side rendering", "translation": "rendu côté serveur (SSR)", "note": "keep the SSR acronym"}, + {"term": "library", "translation": "bibliothèque", "forbidden": ["librairie"]}, + {"term": "form", "translation": "formulaire"}, + {"term": "reactive forms", "translation": "formulaires réactifs"}, + {"term": "signal forms", "translation": "formulaires à base de signals"}, + {"term": "binding", "translation": "liaison", "note": "property binding: liaison de propriété"}, + {"term": "event listener", "translation": "écouteur d'événements"}, + {"term": "lifecycle hook", "translation": "hook de cycle de vie"}, + {"term": "deferrable views", "translation": "vues différables"}, + {"term": "control flow", "translation": "flux de contrôle"}, + {"term": "route", "translation": "route", "note": "feminine: une route"}, + {"term": "router", "translation": "routeur"}, + {"term": "guard", "translation": "garde", "note": "feminine in this context: une garde de route"}, + {"term": "resolver", "translation": "résolveur"}, + {"term": "input", "translation": "input", "note": "the API (input(), @Input) stays in English; 'entrée' for user input in prose, so not a keep term"}, + {"term": "output", "translation": "output", "note": "the API (output(), @Output) stays in English; 'sortie' in prose when not the API"}, + {"term": "build", "translation": "build", "note": "masculine: le build; 'compiler' or 'construire' as a verb in prose"}, + {"term": "deploy", "translation": "déployer"}, + {"term": "bundle", "translation": "bundle", "note": "masculine: un bundle; 'paquet' is acceptable in prose"} +] diff --git a/tools/test/fixtures/example/site.json b/tools/test/fixtures/example/site.json new file mode 100644 index 0000000..be5849b --- /dev/null +++ b/tools/test/fixtures/example/site.json @@ -0,0 +1,36 @@ +{ + "$schema": "../../../site.schema.json", + "lang": "fr", + "name": "Français (exemple)", + "englishName": "French (template example)", + "direction": "ltr", + "domain": "example.invalid", + "upstreamSite": "https://angular.dev", + "repo": { + "owner": "openng-org", + "name": "angular-docs-rosetta", + "branch": "main" + }, + "firebase": { + "projectId": "rosetta-example", + "target": "docs-example" + }, + "search": { + "provider": "none" + }, + "analytics": { + "provider": "none" + }, + "community": { + "chat": "", + "maintainers": [] + }, + "notice": "Traduction communautaire de angular.dev, non affiliée à Google.", + "strings": { + "readInEnglish": "Lire cette page en anglais", + "otherLanguages": "Autres langues", + "outdatedBanner": "Cette traduction est en retard sur la page anglaise ; certains passages peuvent être obsolètes.", + "untranslatedBanner": "Cette page n'est pas encore traduite ; elle est affichée en anglais.", + "reportIssue": "Signaler un problème de traduction" + } +} diff --git a/tools/test/helpers.mjs b/tools/test/helpers.mjs index 0b45b6d..0ff6606 100644 --- a/tools/test/helpers.mjs +++ b/tools/test/helpers.mjs @@ -66,7 +66,9 @@ export async function makeRepo({example = true, git = false, origin = false} = { await mkdir(path.join(root, '.github', 'workflows'), {recursive: true}); await writeFile(path.join(root, '.github', 'workflows', 'template-canary.yml'), 'name: canary\n'); if (example) { - const from = path.join(packageRoot, 'i18n', '_example'); + // A frozen copy of the template's example language: the suite must pass in repositories where + // `create-language --remove-example` deleted i18n/_example. + const from = path.join(fixturesDir, 'example'); const to = path.join(root, 'i18n', '_example'); await mkdir(path.join(to, 'src'), {recursive: true}); for (const f of ['site.json', 'LANGUAGE.md', 'glossary.json', 'README.md']) await cp(path.join(from, f), path.join(to, f)); diff --git a/tools/test/scripts.test.mjs b/tools/test/scripts.test.mjs index ad853e4..e288495 100644 --- a/tools/test/scripts.test.mjs +++ b/tools/test/scripts.test.mjs @@ -44,3 +44,14 @@ describe('package.json scripts', () => { assert.deepEqual(aliases.sort(), subcommands.map(([, name]) => name).sort()); }); }); + +describe('test independence', () => { + test("no test reads the repository's own i18n/ (instances delete i18n/_example)", async () => { + const {readdir} = await import('node:fs/promises'); + const dir = path.join(packageRoot, 'tools', 'test'); + for (const f of (await readdir(dir)).filter((n) => n.endsWith('.mjs'))) { + const src = await read(path.join(dir, f)); + assert.ok(!/packageRoot,\s*'i18n'/.test(src), `${f} reads packageRoot/i18n: use tools/test/fixtures instead`); + } + }); +});