Back to Details

asc-whats-new-writer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

asc What's New Writer

asc What's New 撰写工具

Generate engaging, localized release notes from flexible input. Optionally pair with promotional text updates.
从灵活的输入内容生成引人入胜的本地化发布说明，还可搭配更新推广文本。

Preconditions

前置条件

  • Metadata pulled locally via 
    asc migrate export
    or 
    asc localizations download
    (for keyword reading). OR: user provides keywords manually.
  • Auth configured for upload (
    asc auth login
    or 
    ASC_*
    env vars).
  • The primary locale is 
    en-US
    unless the user specifies otherwise.
  • 通过
    asc migrate export
    或
    asc localizations download
    从本地拉取元数据（用于读取关键词）。或者：用户手动提供关键词。
  • 已配置上传权限（
    asc auth login
    或
    ASC_*
    环境变量）。
  • 除非用户另行指定，否则主区域设置为
    en-US
    。

Before You Start

开始前准备

  1. Read 
    references/release_notes_guidelines.md
    for tone, structure, and examples.
  2. Identify the latest version directory under 
    metadata/version/
    (highest semver). Use this for all metadata reads.
  3. Enumerate existing locales by listing the JSON files in that version directory.
  1. 阅读
    references/release_notes_guidelines.md
    了解语气、结构和示例。
  2. 找到
    metadata/version/
    下的最新版本目录（语义化版本号最高的目录），所有元数据读取操作均使用该目录。
  3. 列出该版本目录下的JSON文件，枚举现有区域设置。

Phase 1: Gather Input

第一阶段：收集输入信息

Accept one of three input modes (auto-detect):
接受以下三种输入模式（自动检测）：

Git Log

Git日志

Parse commits since the last tag:
bash
undefined
解析上次标签之后的提交记录：
bash
undefined

Find latest tag

查找最新标签

git describe --tags --abbrev=0
git describe --tags --abbrev=0

List commits since that tag

列出该标签之后的所有提交

git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges

Filter out noise: merge commits, dependency bumps, CI changes, formatting-only commits. Extract user-facing changes.
git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges

过滤掉无效内容：合并提交、依赖版本更新、CI流程变更、仅调整格式的提交。提取面向用户的变更内容。

Bullet Points

项目符号列表

User provides rough bullets like:
  • "improved search"
  • "fixed crash on launch"
  • "added sleep timer"
用户提供大致的项目符号内容，例如：
  • "搜索功能优化"
  • "修复启动崩溃问题"
  • "新增睡眠计时器"

Free Text

自由文本

User describes changes conversationally:
"We made search faster, fixed that annoying crash when you open the app, and added a sleep timer feature"
The skill extracts and structures the changes from the text.
用户用自然语言描述变更内容，例如：
"我们优化了搜索速度，修复了打开应用时烦人的崩溃问题，还新增了睡眠计时器功能"
本工具会从文本中提取并整理变更内容。

No Input Provided

未提供输入

Prompt the user: "What changed in this release? You can paste git log output, bullet points, or just describe the changes."
向用户提示："本次版本有哪些变更？您可以粘贴git日志输出、项目符号列表，或者直接描述变更内容。"

Phase 2: Draft Notes (Primary Locale)

第二阶段：撰写主区域版本的说明草稿

Step 1: Classify Changes

步骤1：分类变更内容

Group changes into sections per the guidelines:
  • New — new features or capabilities
  • Improved — enhancements to existing features
  • Fixed — bug fixes users would notice
Omit empty sections. If all changes are fixes, only show "Fixed."
根据指南将变更内容分组为以下板块：
  • 新增 — 新功能或新能力
  • 优化 — 现有功能的增强
  • 修复 — 用户可感知的Bug修复
省略内容为空的板块。如果所有变更均为Bug修复，仅保留「修复」板块。

Step 2: Write Benefit-Focused Copy

步骤2：撰写以用户收益为核心的文案

Follow the tone rules from 
references/release_notes_guidelines.md
:
  • Describe user impact, not implementation details
  • Use direct address ("you") and action verbs
  • Be specific — mention concrete improvements
遵循
references/release_notes_guidelines.md
中的语气规则：
  • 描述对用户的实际影响，而非技术实现细节
  • 使用第二人称「你」和动作动词
  • 内容具体明确 — 提及可感知的改进点

Step 3: Front-Load the Hook

步骤3：前置核心亮点

The first ~170 characters are the only visible part before "more." Lead with the single most impactful change in a complete, compelling sentence.
发布说明的前约170字符是「查看更多」按钮前的可见内容。用完整且有吸引力的句子开头，突出最具影响力的变更。

Step 4: Echo Keywords for Conversion

步骤4：融入关键词提升转化

  1. Read 
    keywords
    from 
    metadata/version/{latest}/{primary-locale}.json
  2. If the field is empty or missing, skip this step
  3. Identify keywords relevant to the changes being described
  4. Weave them naturally into the notes — never force or stuff
  1. 从
    metadata/version/{latest}/{primary-locale}.json
    读取
    keywords
    字段
  2. 如果该字段为空或不存在，跳过此步骤
  3. 识别与本次变更相关的关键词
  4. 将关键词自然融入说明内容中 — 切勿生硬堆砌

Step 5: Respect Character Limits

步骤5：遵守字符限制

  • Keep total length between 500-1500 characters in the primary locale
  • This leaves room for localized expansions (some languages expand 30-40%)
  • Hard limit: 4,000 characters
  • 主区域版本的发布说明总长度保持在500-1500字符之间
  • 这为本地化后的内容扩展留出空间（部分语言的内容长度会增加30-40%）
  • 硬性限制：4000字符

Step 6: Optionally Draft Promotional Text

步骤6：可选：撰写推广文本

If the user wants it, draft a 170-char promotional text that:
  • Summarizes the update's theme in one punchy line
  • Can reference seasonal events
  • Is updatable without a new submission
如果用户需要，撰写170字符以内的推广文本，要求：
  • 用一句有力的话总结本次更新的主题
  • 可结合季节性活动
  • 无需重新提交应用即可更新

Present Draft

展示草稿

Show the draft to the user with character count. Wait for approval before localizing.
向用户展示草稿内容及字符数，在本地化前等待用户批准。

Phase 3: Localize

第三阶段：本地化

Translate the approved notes to all existing locales.
将已批准的草稿翻译为所有现有区域的版本。

Translation Rules

翻译规则

  • Use formal register and formal "you" forms (Russian: вы, German: Sie, French: vous, Spanish: usted, Dutch: u, Italian: Lei)
  • Adapt tone to local market — playful English may need adjustment for formal markets (ja, de-DE)
  • Do NOT literally translate idioms — adapt them to local equivalents
  • A playful tone in English may need to be more respectful or formal in other cultures
  • 使用正式语体和正式的「你」称谓（俄语：вы，德语：Sie，法语：vous，西班牙语：usted，荷兰语：u，意大利语：Lei）
  • 根据本地市场调整语气 — 活泼风格的英语版本可能需要调整为更正式的风格（如日语、德语-德国区域）
  • 不要直译习语 — 改用当地文化中的等效表达
  • 英语中的活泼语气在其他文化中可能需要调整为更尊重或正式的风格

Locale-Specific Keyword Echo

区域特定关键词融入

For each locale:
  1. Read 
    keywords
    from 
    metadata/version/{latest}/{locale}.json
  2. Echo locale-specific keywords naturally in the translated notes
  3. If keywords field is empty, skip echo for that locale
针对每个区域设置：
  1. 从
    metadata/version/{latest}/{locale}.json
    读取
    keywords
    字段
  2. 在翻译后的说明内容中自然融入该区域的特定关键词
  3. 如果关键词字段为空，跳过该区域的关键词融入步骤

Validate

验证

  • All translations must be ≤ 4,000 characters
  • Promotional text must be ≤ 170 characters per locale
  • If a translation exceeds the limit, shorten it — never truncate mid-sentence
  • 所有翻译内容的字符数必须≤4000
  • 每个区域的推广文本字符数必须≤170
  • 如果翻译内容超出限制，进行精简 — 切勿在句子中间截断

Phase 4: Review & Upload

第四阶段：审核与上传

Step 1: Present Summary

步骤1：展示摘要

Show a table of all locales with their notes and character counts:
| Locale | What's New (first 80 chars...) | Chars | Promo Text | Chars |
|--------|-------------------------------|-------|------------|-------|
| en-US  | Search just got faster — ...   | 847   | New sleep… | 142   |
| ar-SA  | البحث أصبح أسرع — ...           | 923   | نوم جديد…  | 138   |
| ...    | ...                           | ...   | ...        | ...   |
用表格显示所有区域的说明内容和字符数：
| 区域设置 | What's New（前80个字符...） | 字符数 | 推广文本 | 字符数 |
|--------|-------------------------------|-------|------------|-------|
| en-US  | 搜索速度大幅提升 — ...   | 847   | 全新睡眠… | 142   |
| ar-SA  | البحث أصبح أسرع — ...           | 923   | نوم جديد…  | 138   |
| ...    | ...                           | ...   | ...        | ...   |

Step 2: Wait for Approval

步骤2：等待批准

Do not upload without user confirmation.
未经用户确认不得上传。

Step 3: Upload

步骤3：上传

Upload via 
asc
(verify exact syntax with 
asc --help
):
bash
undefined
通过
asc
工具上传（用
asc --help
验证确切语法）：
bash
undefined

Individual locale

单个区域上传

asc app-info set --app "APP_ID" --locale "en-US" --whats-new "Your release notes here"
asc app-info set --app "APP_ID" --locale "en-US" --whats-new "Your release notes here"

Bulk via .strings files

通过.strings文件批量上传

asc localizations upload --version "VERSION_ID" --path "./localizations"

If promotional text was drafted, upload it separately (no app submission required).
asc localizations upload --version "VERSION_ID" --path "./localizations"

如果撰写了推广文本，单独上传该内容（无需提交新的应用版本）。

Step 4: Handle Failures

步骤4：处理失败

On partial upload failure:
  • Report which locales succeeded and which failed
  • Offer to retry failed locales
出现部分上传失败时：
  • 报告哪些区域上传成功，哪些失败
  • 提供重试失败区域的选项

Metadata File Paths

元数据文件路径

  • Keywords: 
    metadata/version/{latest-version}/{locale}.json
    → 
    keywords
    field
  • Current What's New: 
    metadata/version/{latest-version}/{locale}.json
    → 
    whatsNew
    field
  • Latest version: highest semver directory under 
    metadata/version/
  • Follows the same metadata resolution conventions as 
    asc-aso-audit
  • 关键词： 
    metadata/version/{latest-version}/{locale}.json
    → 
    keywords
    字段
  • 当前What's New内容： 
    metadata/version/{latest-version}/{locale}.json
    → 
    whatsNew
    字段
  • 最新版本： 
    metadata/version/
    下语义化版本号最高的目录
  • 遵循与
    asc-aso-audit
    相同的元数据解析规则

Notes

注意事项

  • What's New is not indexed for App Store search — write for humans, not algorithms.
  • Promotional text is the only metadata field updatable without a new submission.
  • The 170-char visible window is the most important part of your release notes.
  • Each app update triggers algorithm re-evaluation — the act of updating matters, even if the text doesn't affect ranking.
  • Ideal update cadence: every 2-4 weeks.
  • For full metadata translation (all fields), use 
    asc-localize-metadata
    instead.
  • For keyword research and optimization, use 
    asc-aso-audit
    first.
  • What's New不会被App Store搜索索引——为用户撰写，而非算法。
  • 推广文本是唯一无需重新提交应用即可更新的元数据字段。
  • 170字符的可见窗口是发布说明中最重要的部分。
  • 每次应用更新都会触发算法重新评估——更新行为本身很重要，即使文本内容不影响排名。
  • 理想的更新频率：每2-4周一次。
  • 如需完整元数据翻译（所有字段），请改用
    asc-localize-metadata
    。
  • 如需关键词研究和优化，请先使用
    asc-aso-audit
    。