context-extraction

上下文提取

工作流程

命令、筛选条件和文件格式：参见 crowdin-cli 技能的上下文参考。下载前请先阅读；其中的 --status 筛选条件并不表示“需要上下文”。如果已经有 JSONL 文件，请从第 3 步开始。

1. 覆盖情况（可选）：crowdin context status。完成标准：能够告知用户有多少字符串具备人工上下文、AI 上下文或没有上下文。
2. 下载：运行 crowdin context download，不要使用 --status。完成标准：crowdin-context.jsonl 文件已生成，且范围内每个字符串各占一行。
3. 填写 ai_context，遵循本技能其余部分的说明。完成标准：每一行需要上下文的字符串（参见“需要上下文的字符串”）都有值，且每一行经过修改后都通过有效性检查清单。
4. 预览：crowdin context upload --dryrun。完成标准：列出的字符串与已填写的字符串完全一致。
5. 上传：运行 crowdin context upload，然后运行 crowdin context status。完成标准：上传列出的字符串与试运行列出的相同；向用户报告数量和更新后的覆盖情况。

信息来源（按优先级排序）

对于每个字符串，按以下顺序使用这些 JSONL 字段；信息足够编写可信的 ai_context 后即可停止：

1. text——源字符串本身；始终是主要依据
2. key——通常包含结构信息（例如 button.save、modal.title.delete_user、error.network.timeout）
3. context——可能包含自由文本说明、译者备注、源文件引用，也可能为空；将其视为补充信息，不要假设它有固定格式
4. 源文件——仅当 context 包含可解析的文件路径和行号，且字符串仍有歧义时才查阅；读取引用位置前后约 10–15 行，以确定 UI 元素类型、所在组件和属性

需要上下文的字符串

优先处理以下字符串——仅凭 text 和 key 已足够明确的字符串可跳过：

• 有歧义的短词——单个动词、名词或形容词，其含义取决于 UI 中的位置
• 颜色／状态名称——表示颜色、状态或类别的词；可能是标签、徽章或筛选条件
• ICU／消息格式字符串——包含复数形式或命名参数，含义取决于计数对象或替换内容
• 带有内联标签的字符串——包含标记标签，但仅凭字符串本身无法确定被标记部分的作用
• 范围不明确的短语——简短的祈使句或独立短语，可能适用于多种 UI 场景

编写优质的 ai_context 值

• 写 1–3 句话，面向译者，而非开发者
• 说明 UI 元素类型（按钮、标签、选项卡、工具提示、模态框标题、下拉选项等）及其所在位置
• 对于复数形式：说明计数的实体，以及 # 代表什么
• 对于内联标签：说明带标签的部分会呈现为什么形式（链接、代码、粗体文本等）
• 对于颜色／状态名称：说明它是可选选项、徽章、筛选标签等
• 除非文件名和变量名有助于阐明含义，否则避免提及它们

示例

字符串	键	优质的 ai_context
"Red"	color.red	"颜色选择器中的颜色选项标签。表示红色这一可选颜色。"
"Blue"	(无)	"用作可选选项或状态标签的颜色名称。请根据周围的 UI 确认具体含义。"
"{count, plural, one {# month} other {# months}}"	duration.months	"显示以月为单位的时长。'#' 会替换为数字计数。"
"Edit <0>src/App.tsx</0> and save to test HMR"	(无)	"说明性 UI 消息。带标签的部分会呈现为内联代码元素，用于突出显示文件名。"
"New"	button.new	"用于创建新项目的按钮标签。具体创建的实体取决于当前页面的上下文。"

编排输入（可选）

当其他工作流使用额外上下文调用此技能时，请使用这些信息：

• 应用领域 - 用一句话描述产品是什么。在描述界面元素的位置时，可将其作为前缀或融入描述，以消除歧义（“咖啡冲煮记录应用中的按钮标签……”）。
• 源代码检出 - 当 JSONL 的 context 字段包含 #: path:line 引用（PO 上传时会自动添加），且仓库可用时，请阅读周边代码，而不要猜测：识别组件类型、属性以及占位符会被替换成什么。

这两项输入都不会改变以下安全规则——仍然只能编辑 ai_context。

JSONL 文件安全规则

**只能编辑 ai_context 字段值。**切勿触碰 id、key、text、file 或 context。

编辑流程

单个字符串（1–5 行）：使用 StrReplace，限定在确切的行内操作。定位 "ai_context":"" 子字符串（如果已设置，则定位完整的当前值）：

old: "ai_context":""
new: "ai_context":"Your context here."

批量（多个字符串）：当许多行需要上下文时，分批处理，而不是一次处理一个字符串。

• 读取文件的一部分（或文件较小时读取整个文件），找出需要填写 ai_context 的行，为一批行填写上下文（将行解析为 JSON，设置 ai_context，再序列化为单行），然后写入或应用这批更改。对下一批重复此步骤，直至完成。
• 优先分批写入（或应用）行，而不是一次性全局读写，或进行数百次单行替换。批次大小由实施者决定（例如几十行或一百行）。
• 批量处理时，保存前仍须对部分已更改的行应用以下有效性检查清单。

有效性检查清单（保存前验证）

• 该行仍是单个有效的 JSON 对象
• ai_context 值是带引号的字符串
• 值中没有未转义的双引号——使用 \"
• 值中没有字面换行符——保持在同一行
• 没有添加、删除或重新排序字段

字符转义

• " → \"
• \ → \\
• 换行符 → 避免使用；改用空格