Maintain a Multilingual Lesson Library and Keep Translations in Sync With English

## Edit Only Lessons, Articles, and Translations, Not App Code You maintain a content-only repository: instructional lessons, articles, and their translations. The publishing application that renders this content lives elsewhere and is not part of this repository. Your work is prose, structure, and metadata — not application code. Scope boundaries to respect: - Do not add application source code, build tooling, or runtime configuration here. If a change requires the site to behave differently, say so explicitly and describe the companion change needed in the publishing application rather than improvising one here. - Small maintenance scripts that report on the content itself (for example, a translation status report) are legitimate and should be used before editing rather than replaced. - Treat every file as something a human translator will later have to follow. A change that is convenient for you but breaks the translation workflow is a bad change. - When a request is ambiguous about whether it targets the source language or a translation, ask before writing. Guessing wrong silently corrupts the staleness tracking described later. ## Mirror Folders Across Languages and Change the English Source First The library uses a predictable, mirrored layout. Lesson files live under a lessons directory, then a folder named for the ISO language code, then a category folder, then the document itself. Blog posts live in a single posts directory and are named with a date prefix followed by a hyphen-separated slug, so that chronological order is visible from the filename alone. The category set under each language is fixed and identical across all languages. Common categories are basics, intermediate, advanced, storage, testing, data processing, framework-specific material, and a miscellaneous bucket. Do not invent a category in one language only; add it everywhere or nowhere. One language — normally English — is the single source of truth. Every other language directory holds translations of it. Rules that follow from this: - Substantive changes are made in the source language first, then propagated to translations. Never introduce new facts, examples, or sections into a translation alone. - A translation may be corrected on its own only for translation-quality reasons: mistranslation, grammar, typography, or locale conventions. - If you notice an error in a translation that also exists in the source, fix the source and treat the translation as a follow-up. ## Raise the Version Number by Change Size and Copy It Into Translations Every document opens with a structured metadata block terminated by a separator line. The block carries at minimum a version string, a title, and a short excerpt that summarizes the document in one or two sentences. Article-style posts additionally carry an author name, an author link, tags, and a publication date. The version field is not decoration — it is machine-read. A translation copies the exact version of the source document it was translated from. Tooling then compares each translation's version against the current source version to decide whether that translation is current, lightly stale, or badly stale. Bump the source version according to the size of the change: - Major: the document was largely rewritten. Translators must redo their work. - Minor: sentences, paragraphs, or examples were added or removed. Translators must review and patch. - Patch: spelling and typographical corrections only. Translations remain usable. Never bump a version without making the corresponding change, and never make a substantive change without bumping. Both errors destroy the accuracy of staleness reporting, which is the only mechanism keeping the translated library honest. When editing a translation, update its version only when you have actually brought it in line with the newer source content. ## Write in a Shared 'We' Voice With Examples Before Explanations Apply these conventions to all content unless a locale guide overrides them. - Use inclusive first-person plural. The reader is a collaborator working alongside you, not a pupil being lectured. Avoid "you must" phrasing where "we" reads naturally. - Show first, explain second. A worked example precedes its explanation; the reader sees the thing before reading about the thing. - Keep paragraphs short. When information gets dense, convert it into a bulleted list or an example block rather than a long paragraph. - Use active voice. Use contractions consistently rather than expanded formal forms. - No emoji. No platitudes, no congratulatory filler, no sentences that exist only to introduce the next sentence. - Use the serial comma. - Heading levels: second-level headings for major sections, third-level for subsections. Never place a top-level heading inside body content — that level belongs to the document title. - Every example block declares its language identifier so the renderer can highlight it correctly. Cut anything that does not teach. Length is not a virtue; a shorter document that a translator can render faithfully is worth more than a longer one that drifts. ## Order Each Lesson From Overview to Examples to Related Topics Instructional documents follow a fixed narrative shape: 1. A brief overview of what the document covers. 2. Motivation — why this matters — in two or three sentences at most. Resist expanding this section; it is the most common place where filler accumulates. 3. Core content, driven by concrete examples with explanation following each one. 4. Connections outward: how this topic relates to adjacent material the reader has seen or will see next. Within the core content, order material from the simplest usable case to the more complex variations, and introduce a term before relying on it. If a document grows to cover two clearly separable topics, split it rather than letting it sprawl — two focused documents translate better and go stale independently. The excerpt in the metadata block should be writable from the overview alone. If you cannot summarize the document in one or two sentences, the document is doing too much. ## Add New Lessons or Languages and Flag the Site Registration Needed New source document: create the file under the source language directory in the correct category, with a complete metadata block including an initial version. Then state clearly whether a companion change is required in the publishing application to register the new document for display. Do not assume it appears automatically. New translation: copy the source file into the target language directory at the same category path and filename, translate the body, and translate the human-readable metadata values such as title and excerpt. Leave the structural field names and the version value untouched — the version must match the source exactly. New language: create the full set of category directories under the new language code so the layout mirrors every other language, add the first translated documents, and register the language with the publishing application. A language folder that exists but is not registered produces content nobody can reach. Before writing any translation, read the locale-specific style note for that language if one exists. Locale notes cover terminology choices, transliteration of technical terms, punctuation, and honorific register, and they override the general house style where they conflict. If no locale note exists for a language you are asked to translate into, propose creating one rather than inventing conventions silently. ## Use the Status Report to Update the Most Outdated Translations First Translation drift is the default failure mode of a multilingual library. Manage it deliberately. Start any translation session by running the status report over the library rather than browsing directories by hand. Filter it to the languages you are responsible for and to the severity levels that matter — documents missing entirely and documents flagged as majorly stale come first, minor drift second, patch-level drift last or never. Working rules: - Do not partially translate a document and leave the version matching the source. A half-finished translation that reports itself as current is worse than an obviously missing one. - If you must stop midway, leave the version at its previous value so the report keeps flagging the file. - Do not machine-translate and ship without review against the locale note. - When the source changes after you began, re-check the diff before finishing; finish against the version you will actually record. - Report at the end which documents you brought current, which you deliberately skipped, and why — the next contributor triages from that.