Internationalization (i18n) following good practices#1344
Open
1000i100 wants to merge 4 commits into
Open
Conversation
1000i100
force-pushed
the
i18n-multilingual
branch
2 times, most recently
from
3684adb to
7ff8c25
Compare
Make the site translatable without changing the English site. jekyll-polyglot serves the default language at the root and each other language under its own prefix from the same sources, with automatic fallback to English. Adds the translation lookups (t.html / tmd.html), the no-JS language selector plus a progressive browser-language suggestion, localized hreflang/canonical/og:locale, and a per-language Markdown page mechanism (i18n/<lang>/<page>.md overrides the English page, which is the fallback). Translations live in two mirrored trees, each with a README: _data/i18n/<lang>/ holds the keyed strings (YAML) and i18n/<lang>/ holds the prose pages (Markdown). Because polyglot isn't a GitHub Pages plugin, the site is built and deployed via a GitHub Actions workflow (the only one-time maintainer step: set Pages' source to "GitHub Actions"). Includes a small non-blocking i18n spec, the English base (_data/i18n/en/ui.yml), and docs (TRANSLATING.md, WEBLATE.md). No language other than English is enabled yet, so there is no visible change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Enable French (fr): the interface, rule labels and license summaries (_data/i18n/fr/*) plus the French prose pages (i18n/fr/*.md). It's an initial, partially-reviewed translation meant to be refined by the community via Weblate; anything missing falls back to English. French is included as the maintainer's native language and the most-reviewed in the demo. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Enable es, pt, zh, ko and ar: their interface/summaries/rules data and prose pages (i18n/<lang>/*.md), each falling back to English where incomplete. These are initial, AI-assisted drafts to be refined via Weblate, seeded by earlier requests — Spanish (github#1034), Portuguese (github#586), Chinese (github#67, github#72), Korean (github#62). Arabic is included to exercise right-to-left support (text_direction drives <html dir> with a [dir="rtl"] mirror; the legal <pre> stays ltr). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
So the site also works when served from a sub-path (e.g. a GitHub Pages project site, or a staging deploy) — not only at a domain root. Root-relative links in page bodies and license summaries are prefixed with site.baseurl at a single injection point, the chrome uses relative_url, and the deploy builds with the base path GitHub Pages reports (actions/configure-pages' base_path). When baseurl is empty (a domain root, e.g. the upstream site) every change is a no-op. This is independent of the i18n feature; it's kept as its own commit so it can be reviewed — or dropped — on its own. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1000i100
force-pushed
the
i18n-multilingual
branch
from
7ff8c25 to
6fc150f
Compare
Author
|
@mlinksva could you review this PR ? I would like to know if merging it is an option (perhaps with some changes, tell-me), or if I should register another domain name to host an i18n fork ? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This adds multilingual support. It leads with the live demo and the
practices you've asked for in the past (#68, #586), to show up front they're respected.
Good practices requested in #68 / #586 — and how this PR follows them
_licenses/*.txtbody isbyte-for-byte unchanged; only the non-legal summaries and the interface are translated.
unchanged, so
licenseeand the existing specs see exactly what they see today..txtfront matter, rule labels in_data/rules.yml; translations are overlays withautomatic fallback to English. (Prose pages are one file per language — a translation,
not a copy of the English page.)
/licenses/mit/is still English; only translationsare prefixed (
/fr/…). No/en-US/redirects.(English fallback) — see Tests.
own URL; JS only adds conveniences (remembering a choice, suggesting the browser
language), never a forced redirect.
with Weblate (see WEBLATE.md), translations are maintained by the
community with minimal effort from you — you mostly review and merge the pull requests
Weblate opens, and an incomplete or outdated language always falls back to English, so
nothing breaks.
_config.yml; from thereevery translation file — the YAML overlays and the per-page Markdown — is optional,
with English filling in anything left untranslated.
What it adds
Per-language URLs via
jekyll-polyglot, generated from the single English sources.A deliberate split, so the right people work on the right parts and legal text is
never touched:
_data/i18n/<lang>/ui.yml,rules.ymlabout.<lang>.md, …description/how/note_data/i18n/<lang>/licenses.yml.txtfront matter_licenses/*.txtSEO:
hreflang+x-default, localized<html lang>/dir(RTL), per-language<title>, meta description, Open Graph andog:locale, sitemap with the translated URLs.Docs: TRANSLATING.md and WEBLATE.md.
Languages
The non-English translations are initial, AI-assisted drafts to be refined by native
speakers via Weblate.
Build & deploy
jekyll-polyglotisn't a GitHub Pages plugin, so the site must be built and deployed by aGitHub Actions workflow (the opensource.guide approach), with the base path taken from
actions/configure-pagesso the same workflow serves a domain root or a sub-path. Thisexact pipeline runs the live demo above. The only manual, one-time step:
Tests
Existing specs and HTML-Proofer pass.
spec_helperskips polyglot during the baresite.readso collection counts stay exact. A small, non-blockingspec/i18n_spec.rbguards the i18n layer — it flags a template referencing a missing key or a translation
using an unknown key/id, but never requires a translation to be complete. So community
translation PRs are validated automatically, at no cost to you.
How this PR is organized (4 commits)
visible change to the English site.
root). Independent of i18n; kept separate so you can review or drop it alone.
Each commit stands on its own, so you can review — or even merge — them incrementally.