ADR-0009: English documentation, Arabic-first product

• Date: 2026-09-18
• Status: Accepted
• Deciders: the owner, Claude
• Tags: strategy brand

Context

The seed documents were written in Arabic (the documentation-language choice was still open: Arabic docs + English code, or English only). The foundation is now an English-language upstream (supastarter, AGENTS.md), the Handbook is rendered by apps/docs, and non-Arabic contributors and tooling (linters, code review, upstream merges) need to read every document. At the same time the product serves Saudi shop owners who run their business from a phone in Arabic.

Decision

Repository language is English; product language is Arabic first.

• All documentation under docs/, code comments, commit messages, pull request descriptions, and guide text in the repo are written in English.
• Arabic appears in the repo only as data: product labels, UI translations under packages/i18n/translations/ar, and mail templates.
• The product UI defaults to ar (RTL) with en as the second locale; every user-facing string goes through next-intl.
• Conversations with the owner may be in Arabic; artefacts committed to the repo are not.
• ADRs follow docs/adr/0000-template.md and keep the "Revenue impact (monthly, confidence)" line.

Consequences

• Positive — one language for code, docs, upstream, and tooling; reviewable by any contributor; the handbook renders cleanly in Fumadocs.
• Negative — the owner reads product strategy in a second language; Arabic-only stakeholders need a translated brief when one is required.
• Revenue impact (monthly, confidence) — none directly; lowers onboarding cost for developers and agents (medium confidence).

Rejected alternatives

• Arabic docs + English code (the seed's interim choice): two languages in one repo, poor tooling support, unreadable to upstream reviewers.
• English UI by default: contradicts the ICP and the "Arabic first, RTL native" principle.

References

• ADR-0008, docs/index.md