README Internationalization (i18n)

README.md

• read the source-of-truth README
• create localized sibling files such as

  README.zh.md

• preserve GitHub-flavored Markdown structure and repo-specific tokens
• add or update a shared language selector near the top of every variant

Inputs

• source README path, default

  README.md

• source language, default inferred or English
• one or more target languages
• optional glossary or do-not-translate list
• optional filename override if the repo already uses a different multilingual naming pattern

Defaults And Decision Rules

• Treat the root

  README.md

  as the source-of-truth unless the user explicitly says otherwise.
• If the source language is ambiguous, ask once. Otherwise assume English.
• Keep section order aligned with the source README. Only make a small heading wording adjustment when needed to produce a valid localized anchor.
• Output localized siblings with

  README.<bcp47-tag>.md

  naming unless the repo already has a different established pattern that should be preserved.
• Update an existing language selector in place. Do not duplicate it.
• Translate only human-language content.
• Preserve project names, package names, commands, CLI flags, option names, environment variables, URLs, file paths, inline code, code fences, HTML attributes, and badge/image URLs.
• Badge alt text or visible labels may be translated only when the change does not require changing the badge URL, query params, or image source.
• If a glossary or do-not-translate list is provided, apply it consistently across every target language.

Workflow

1. Establish the source README and languages

• Confirm the source README path. Default to

  README.md

  .
• Identify the source language from the file contents and repo context.
• Determine target languages from the request or existing repo pattern.
• Note any glossary terms, product names, or phrases that must stay untranslated.

2. Audit the Markdown structure before translating

references/preservation-checklist.md

• headings and heading levels
• badge rows, shields URLs, and image links
• tables and alignment rows
• raw HTML blocks and inline HTML
• GitHub alerts or admonitions such as

  > [!NOTE]

• code fences, inline code, commands, and config snippets
• intra-document anchors such as

  (#installation)

• relative links to files, docs, screenshots, or other README variants

3. Translate only the prose layer

• paragraph text
• list item prose
• table cell prose
• visible text inside HTML blocks
• image alt text when safe
• selector labels and other human-facing labels

• fenced code blocks
• inline code spans
• shell commands
• flags such as

  --help

• env vars such as

  OPENAI_API_KEY

• URLs
• file paths
• repo/package/project identifiers
• badge and image URLs

4. Preserve structure while writing the localized README

• Keep the same heading hierarchy and section order as the source.
• Keep the same number of code fences unless the user explicitly asks to rewrite examples.
• Preserve table shape, list nesting, HTML wrappers, and Markdown comments.
• Preserve relative links unless a link intentionally needs to point at a localized sibling README.

5. Rewrite localized anchors and anchor-dependent links

• rewrite every same-file

  (#...)

  link so it matches the localized heading slug in that file
• preserve custom explicit anchors such as

  <a id="...">

  unless the file already uses localized explicit IDs
• verify that every intra-document anchor target resolves to an existing heading or explicit anchor

6. Write sibling files using the repo's naming pattern

• README.zh.md

• README.es.md

• README.fr.md

7. Insert or update the language selector

references/language-selector-reference.md

• keep the selector near the top of the file
• if the README starts with a title, badges, hero image, or short intro block, place the selector immediately after that opening cluster

• update an existing selector block in place if one already exists
• if you add a new selector, use the canonical marker comments from the reference file so later runs can update it deterministically
• emphasize the current language and link the other variants
• keep selector order and labels consistent across every README variant

8. Final verification

• localized filenames follow the chosen pattern
• every README variant contains exactly one selector block
• code fence counts are preserved
• badge/image URLs and relative file links still point to the original targets unless intentionally localized
• every

  (#...)

  link resolves inside its own file
• the localized README still feels structurally identical to the source

Output

• one localized sibling README per target language
• an updated selector block in every README variant
• a brief note to the user covering created or updated files, any assumptions, and any terms intentionally left untranslated

Maintenance Note

README.md

Example Prompts

Translate this README into Chinese and add a language switcher. Keep badge URLs, code fences, and all commands exactly as they are.

Make the repo multilingual. Add Spanish and Chinese README variants, keep the internal anchor links working, and wire the selector into every file.

We already have README.zh.md. Add README.es.md and update the existing selector in place instead of adding a second one.

Common Mistakes

• Translating fenced code blocks or inline code instead of only the prose around them
• Duplicating the language selector instead of updating the existing block
• Translating a heading but forgetting to rewrite same-file

  (#...)

  links
• Changing badge URLs or image sources while trying to translate visible labels
• Reordering sections in the localized README even though the source README is the authority