readme-i18n

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

README Internationalization (i18n)

README 国际化（i18n）

Localize a repository

README.md

without breaking the repo mechanics around it.

The default job is translate + wire-up:

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

This skill is for multilingual README workflows, not general website/app i18n.

在不破坏仓库相关机制的前提下，对仓库的

README.md

进行本地化处理。

默认任务为翻译+关联配置：

读取作为权威来源的README
创建本地化的同级文件，如
```
README.zh.md
```
保留GitHub风格Markdown的结构和仓库特定的标识
在每个变体文件顶部附近添加或更新共享的语言选择器

本技能适用于多语言README工作流，而非通用网站/应用的国际化。

Inputs

输入参数

Expect these inputs when available:

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

If target languages are not named, inspect existing translated files, selectors, filenames, issues, or prior repo conventions. If that still leaves the target languages unclear, ask once. Do not invent target languages.

若有可用信息，需获取以下输入：

源README路径，默认为
```
README.md
```
源语言，默认自动推断或设为英语
一种或多种目标语言
可选的术语表或不翻译列表
若仓库已使用不同的多语言命名规则，可选择覆盖文件名

若未指定目标语言，需检查已有的翻译文件、选择器、文件名、议题或仓库过往惯例。若仍无法明确目标语言，询问一次即可，不要自行设定目标语言。

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.

除非用户明确说明，否则将根目录下的
```
README.md
```
视为权威来源。
若源语言不明确，询问一次；否则默认英语。
保持章节顺序与源README一致。仅在需要生成有效的本地化锚点时，对标题措辞进行小幅调整。
输出的本地化同级文件默认采用
```
README.<bcp47-tag>.md
```
命名规则，除非仓库已有需保留的既定命名模式。
原地更新现有的语言选择器，不要重复添加。
仅翻译自然语言内容。
保留项目名称、包名、命令、CLI标志、选项名称、环境变量、URL、文件路径、行内代码、代码块、HTML属性以及徽章/图片URL。
仅当修改不需要更改徽章URL、查询参数或图片源时，才可翻译徽章的替代文本或可见标签。
若提供了术语表或不翻译列表，需在所有目标语言中统一应用。

Workflow

工作流程

1. Establish the source README and languages

1. 确定源README与语言

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.

确认源README路径，默认为
```
README.md
```
。
根据文件内容和仓库上下文识别源语言。
根据用户请求或仓库现有模式确定目标语言。
记录任何必须保留不翻译的术语、产品名称或短语。

2. Audit the Markdown structure before translating

2. 翻译前审核Markdown结构

Read the source README once as structure, not prose. Open

references/preservation-checklist.md

and inventory the elements most likely to break:

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

If the README already has localized siblings, inspect them too before choosing filenames or selector style.

先将源README视为结构而非文本进行阅读。打开

references/preservation-checklist.md

，统计最容易出错的元素：

标题及标题层级
徽章行、Shields URL和图片链接
表格及对齐行
原始HTML块和行内HTML
GitHub提示框或警示信息，如
```
> [!NOTE]
```
代码块、行内代码、命令和配置片段
文档内锚点，如
```
(#installation)
```
指向文件、文档、截图或其他README变体的相对链接

若README已有本地化的同级文件，在选择文件名或选择器样式前也需检查这些文件。

3. Translate only the prose layer

3. 仅翻译文本内容

Translate:

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

Do not translate:

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

When in doubt, preserve the literal token and translate the surrounding sentence instead.

需要翻译的内容：

段落文本
列表项文本
表格单元格文本
HTML块内的可见文本
安全情况下的图片替代文本
选择器标签及其他面向用户的标签

无需翻译的内容：

代码块
行内代码
Shell命令
标志，如
```
--help
```
环境变量，如
```
OPENAI_API_KEY
```
URL
文件路径
仓库/包/项目标识符
徽章和图片URL

若不确定，保留原标识并翻译其周围的句子即可。

4. Preserve structure while writing the localized README

4. 编写本地化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.

保持与源README相同的标题层级和章节顺序。
除非用户明确要求重写示例，否则保留代码块的数量。
保留表格格式、列表嵌套、HTML包装器和Markdown注释。
保留相对链接，除非链接需要指向本地化的同级README。

5. Rewrite localized anchors and anchor-dependent links

5. 重写本地化锚点和依赖锚点的链接

When a translated heading changes, GitHub will generate a different heading ID. After translating headings:

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

Prefer a small heading wording adjustment over a broken anchor. The section order should still match the source README.

当翻译后的标题发生变化时，GitHub会生成不同的标题ID。翻译标题后：

重写所有文档内的
```
(#...)
```
链接，使其与该文件中的本地化标题slug匹配
保留自定义的显式锚点，如
```
<a id="...">
```
，除非文件已使用本地化的显式锚点
验证每个文档内的锚点链接都能指向对应的标题或显式锚点

优先对标题措辞进行小幅调整，而非保留无效的锚点。章节顺序仍需与源README一致。

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

6. 按照仓库的命名规则编写同级文件

Default to sibling filenames like:

```
README.zh.md
```
```
README.es.md
```
```
README.fr.md
```

If the repo already uses a different multilingual naming pattern, keep using it consistently rather than forcing the default pattern.

默认的同级文件名格式如下：

```
README.zh.md
```
```
README.es.md
```
```
README.fr.md
```

若仓库已有不同的既定多语言命名模式，需保持该模式一致，而非强制使用默认格式。

7. Insert or update the language selector

7. 插入或更新语言选择器

Open

references/language-selector-reference.md

before editing selectors.

Placement:

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

Behavior:

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

在编辑选择器前，打开

references/language-selector-reference.md

。

放置位置：

将选择器放在文件顶部附近
若README以标题、徽章、首图或简短介绍开头，将选择器紧跟在这些开头内容之后

行为规则：

若已有选择器块，原地更新
若添加新选择器，使用参考文件中的标准标记注释，以便后续运行时能确定性地更新它
突出显示当前语言，并链接到其他变体
在所有README变体中保持选择器的顺序和标签一致

8. Final verification

8. 最终验证

Before finishing, verify:

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

完成前，需验证：

本地化文件名符合所选模式
每个README变体仅包含一个选择器块
代码块数量保持不变
徽章/图片URL和相对文件链接仍指向原始目标，除非是有意本地化的
每个
```
(#...)
```
链接在其所在文件内均可正常解析
本地化后的README在结构上与源README保持一致

Output

输出结果

Produce:

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

生成以下内容：

每个目标语言对应一个本地化的同级README
每个README变体中更新后的选择器块
给用户的简短说明，包含创建或更新的文件、任何假设前提，以及有意保留不翻译的术语

Maintenance Note

维护说明

Keep

README.md

as the canonical source unless the user says otherwise. When the source README changes later, update each localized sibling by diffing the changed prose, then re-check selectors, filenames, and anchor links instead of reformatting the whole file from scratch.

除非用户另有说明，否则将

README.md

视为权威来源。当源README后续发生变更时，通过对比变更的文本内容来更新每个本地化的同级文件，然后重新检查选择器、文件名和锚点链接，而非从头开始重新格式化整个文件。

Example Prompts

示例提示

Example 1

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

Example 2

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

Example 3

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

示例1

将此README翻译成中文并添加语言切换器。请完全保留徽章URL、代码块和所有命令。

示例2

让仓库支持多语言。添加西班牙语和中文的README变体，确保内部锚点链接可用，并在所有文件中配置选择器。

示例3

我们已有README.zh.md。添加README.es.md，并原地更新现有的选择器，不要添加第二个选择器。

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

翻译代码块或行内代码，而非仅翻译其周围的文本
重复添加语言选择器，而非更新现有块
翻译了标题但忘记重写文档内的
```
(#...)
```
链接
尝试翻译可见标签时更改了徽章URL或图片源
即使源README是权威版本，仍对本地化README的章节进行重新排序",