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 into canonical files via 
    asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata"
    . 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 metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata"
    命令将元数据本地拉取到标准文件中。或者：用户手动提供关键词。
  • 已配置上传权限（使用
    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

Find latest tag

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

List commits since that tag

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修复
省略空白板块。若所有变更均为修复内容，则仅显示"修复"板块。

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
    • These canonical files are also what 
      asc metadata keywords ...
      reads and writes.
  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
    字段
    • 这些标准文件也是
      asc metadata 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   |
| ...    | ...                           | ...   | ...        | ...   |
展示包含所有区域设置、对应发布说明及字符数的表格：
| 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   |
| ...    | ...                           | ...   | ...        | ...   |

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 direct update

Individual locale direct update

asc apps info edit --app "APP_ID" --version-id "VERSION_ID" --locale "en-US" --whats-new "Your release notes here"
asc apps info edit --app "APP_ID" --version-id "VERSION_ID" --locale "en-US" --whats-new "Your release notes here"

Bulk canonical-metadata push after writing ./metadata/version/<version>/<locale>.json

Bulk canonical-metadata push after writing ./metadata/version/<version>/<locale>.json

asc metadata push --app "APP_ID" --version "1.2.3" --dir "./metadata" --dry-run asc metadata push --app "APP_ID" --version "1.2.3" --dir "./metadata"

If promotional text was drafted, either include `--promotional-text "..."` in the direct update command or write `promotionalText` into the canonical JSON before `asc metadata push`.
asc metadata push --app "APP_ID" --version "1.2.3" --dir "./metadata" --dry-run asc metadata push --app "APP_ID" --version "1.2.3" --dir "./metadata"

若已撰写推广文案，可在直接更新命令中添加`--promotional-text "..."`参数，或在执行`asc metadata push`前将`promotionalText`写入标准JSON文件。

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/
  • The canonical 
    ./metadata
    tree is what 
    asc metadata pull
    , 
    asc metadata push
    , and 
    asc metadata keywords ...
    operate on.
  • Follows the same metadata resolution conventions as 
    asc-aso-audit
  • 关键词： 
    metadata/version/{latest-version}/{locale}.json
    → 
    keywords
    字段
  • 当前发布说明： 
    metadata/version/{latest-version}/{locale}.json
    → 
    whatsNew
    字段
  • 最新版本： 
    metadata/version/
    下语义化版本号最高的目录
  • 标准
    ./metadata
    目录结构是
    asc metadata pull
    、
    asc metadata push
    和
    asc metadata keywords ...
    命令的操作对象。
  • 遵循与
    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.
  • If the local keyword field is stale before drafting, refresh it with 
    asc metadata pull
    or inspect planned keyword changes with 
    asc metadata keywords diff
    .
  • What's New内容不会被App Store搜索索引——请面向用户撰写，而非算法。
  • 推广文案是无需提交新版本即可更新的唯一元数据字段。
  • 170字符的可见区域是发布说明中最重要的部分。
  • 每次应用更新都会触发算法重新评估——更新行为本身很重要，即使文案不影响排名。
  • 理想的更新频率：每2-4周一次。
  • 若需翻译所有元数据字段，请使用
    asc-localize-metadata
    工具。
  • 进行关键词研究和优化时，请先使用
    asc-aso-audit
    工具。
  • 若撰写前本地关键词字段已过时，可使用
    asc metadata pull
    命令刷新，或通过
    asc metadata keywords diff
    命令查看计划中的关键词变更。