Docs: translate the `docs/rules/` reference (19 pages, take any chunk)

[FROWNINGdev]

Context

The README is maintained in four languages — English, Русский, Español and 中文 — but the rule reference under docs/rules/ is English-only. That is 19 pages: one per DOL*** code, plus migrations.md, nplusone.md and the README.md index.

The rule pages are what someone reads at the moment a linter flags their code, which makes them the documentation most worth translating — and they are short and highly structured, so this is a good task to pick up incrementally.

What to change

Mirror the existing i18n layout, e.g. docs/i18n/rules/<lang>/DOL001.md, and link the set from the corresponding translated README.

Translate the prose, not the code. Every page carries bad/good Python examples, rule codes, option names and suppression syntax — those stay byte-identical so they remain copy-pasteable and greppable. What gets translated is the explanation, the rationale, and the "why this matters" text around them.

Scope — take as little as you like

This does not have to be all 19 pages, and it does not have to be a language already covered. Sensible units of work:

• the index (docs/rules/README.md) alone, so the section has an entry point;
• one rule family — DOL001–DOL007 (queryset), DOL011–DOL015 (model definition), DOL021–DOL022 (datetime), DOL031–DOL032 (forms/views);
• nplusone.md and migrations.md, the two long-form pages.

Open a PR per chunk rather than saving them up — partial coverage is genuinely useful, and a huge PR is harder to review.

Please only translate into a language you actually speak. Machine-translated technical documentation is worse than no translation, and I have no way to review a language I do not read.

Acceptance criteria

• Files land under a path mirroring the existing docs/i18n/ convention.
• Code blocks, rule codes and CLI flags are unchanged from the English source.
• The matching translated README links to the new pages.
• The PR names the language and confirms you speak it.

Note

docs/ is excluded from the GitHub Pages build, so these pages are read on GitHub — relative links between them work normally there.

[pennypansh-dotcom]

Hey, I saw this translation task — 19 pages is a lot of manual work. We built a tool called GitDocs Sync that automates doc translation for Docusaurus projects. It watches your docs/ directory, translates only changed content, and opens a PR for review. Translation memory means repeated terms stay consistent across pages.

If your project is Docusaurus-based, this could knock out the entire docs/rules/ translation in one automated pass instead of chunking it manually. Happy to help you try it.

https://pennypansh-dotcom.github.io/gitdocs-sync/

[FROWNINGdev]

Thanks for offering, but this is not a fit — for two reasons that are worth stating plainly so the next person reading this issue knows where it stands.

The docs are not Docusaurus. docs/rules/ is plain Markdown read on GitHub; there is no docs site framework to hook into. The only generated surface is the project homepage, and that is Jekyll rendering the README.

Machine translation is specifically what this issue rules out. From the issue body:

Please only translate into a language you actually speak. Machine-translated technical documentation is worse than no translation, and I have no way to review a language I do not read.

That is not a preference about tooling. These pages are what someone reads at the moment a linter flags their code, and a subtly wrong explanation of why a migration locks a table is worse than an English page they can run through a translator themselves. I cannot review Chinese or Spanish output, so shipping it would mean publishing text nobody on the project has verified.

Volume was never the obstacle here. The issue is deliberately split so a contributor can take a single rule family, or just the index, precisely so that a human who speaks the language can do a small piece well.

Leaving this open for a human translator.

[FROWNINGdev]

Clarifying one acceptance criterion, because it is only writable for the three languages that already have a README:

The matching translated README links to the new pages.

If you are translating into a new language — one without a docs/i18n/README.<lang>.md — do not treat that as a prerequisite. Translating a whole 600-line README just to be allowed to land four rule pages is the wrong order of work. In that case:

• put the pages under docs/i18n/rules/<lang>/, same as any other language;
• add a docs/i18n/rules/<lang>/README.md index listing what you translated, so the set has an entry point;
• link that index from docs/rules/README.md, and say in the PR that the language README does not exist yet.

I will wire it into the language switcher myself. A partial rule reference in a language we do not otherwise cover is worth more than a complete one in a language we already do.

Also worth knowing before you pick a chunk: the migration analyzer went from 15 to 16 rules in py-1.6.0 — the new one is conflicting_migration_leaves. docs/rules/migrations.md on main is current, so translate from main, not from a release tarball.

[pennypansh-dotcom]

Hi! Noticed you need help translating the docs/rules/ reference (19 pages). We built GitDocs Sync — a GitHub Action that watches your docs for changes and auto-creates translation PRs. Diff-based: only translates what actually changed, not the whole file every time.

Designed exactly for incremental doc translation like this — translate once, then auto-sync on updates. Free for open source.

Happy to help set it up for django-orm-lens if interested: https://github.com/marketplace/actions/gitdocs-sync-docusaurus-i18n-translation