docs(rfc): 0001 — documentation i18n strategy#284
Merged
Conversation
Refs #239. Decides what happens to the three existing non-English locales (pt-BR, es, zh-Hans) after the Docusaurus → Fumadocs migration. Recommendation: freeze translations at migration time, ship EN-only Fumadocs first, revisit localization as a separate initiative once the EN source stabilizes. Four options evaluated: A. Freeze and archive (recommended) B. Continuous LLM-assisted machine translation C. Crowdin or equivalent managed pipeline D. Delete the translations Key reasoning: - We have no sustained translation contributors or QA process - Shipping translations without commitment = anti-product (violates Manifesto principle 6) - Archive (not delete) preserves work for future re-engagement - EN surface is still shifting weekly in Phase 0 — translating moving targets is wasted motion - Deferring execution lets us pick B or C later with traffic data from PostHog (PR #277) Implementation plan (to land alongside docs.agentskit.io promotion): - Move apps/docs/i18n/* to apps/docs/archive-i18n/ with a README - Add Vercel/CF Pages locale-aware redirects with a one-time banner - Document the decision in Contributing / Translations page - Add PostHog dashboard for archived locale path traffic - Retire i18n from the Docusaurus build Criteria for reopening (not dates): - Sustained external contributor coverage - Corporate sponsor funding - Traffic data showing ≥10% locale traffic - AgentsKit-hosted translation agent reaching acceptable quality Also creates rfcs/README.md with process notes distinguishing RFCs (reversible proposals) from ADRs (shipped decisions). Refs #239 #211 #277 #243
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.
Summary
Proposes the i18n path for the Fumadocs migration. Refs #239.
Recommendation: freeze the three existing non-English locales (pt-BR, es, zh-Hans) at migration time, ship EN-only Fumadocs first, revisit localization as a separate initiative once the EN source stabilizes.
The four options
Why freeze
Implementation plan (lands alongside docs.agentskit.io promotion)
apps/docs/i18n/*→apps/docs/archive-i18n/with a README pointing to this RFCcontributing/translations.mdxCriteria for reopening (not calendar-driven)
Not on the list: calendar time, pressure without contributor commitment, competitive parity.
What this PR contains
rfcs/README.md— RFC process notes, distinction from ADRsrfcs/0001-i18n-strategy.md— the full proposalTest plan
Refs #239 #211 #277 #243