objectstack-ai · os-zhuang · Aug 19, 2026 · Aug 18, 2026 · Aug 18, 2026
diff --git a/.changeset/i18n-merge-consequence-documented.md b/.changeset/i18n-merge-consequence-documented.md
@@ -0,0 +1,22 @@
+---
+"@objectstack/cli": patch
+---
+
+docs(cli): document the i18n merge consequence for a corrected source string (#9672)
+
+`os i18n extract` merges against committed bundles by default so a re-run never
+wipes a hand translation, and `--fill=default` only fills gaps. That means a
+source label/description that is later **corrected** does not propagate into a
+locale that already holds a translation of the old text — a present-but-stale
+string is not a gap, so it is left as-is. This was always the behaviour and
+remains unchanged; it was simply undocumented where the next reader looks.
+
+Two places now say so: the merge-options comment in `os i18n extract`'s command
+implementation, and the header comment written into every generated
+`<locale>.objects.generated.ts` / `<locale>.metadata-forms.generated.ts` bundle.
+Committed bundles across the repo are regenerated so their header matches the
+new template (translated content is unchanged).
+
+`check:i18n`'s bundle-drift verdict still proves generated output matches the
+schema; it does not compare a translated value against its source's meaning
+(that remains an open appetite question, tracked separately — see #9672).
diff --git a/packages/cli/src/commands/i18n/extract.ts b/packages/cli/src/commands/i18n/extract.ts
@@ -136,6 +136,16 @@ export default class I18nExtract extends Command {
  locales,
  fill: flags.fill as FillStrategy,
  filter,
+ // Merge (the default) never overwrites an existing non-default-locale
+ // entry, so correcting a source label/description does not propagate
+ // into a locale that already holds a translation of the old text —
+ // a present-but-stale string is not a gap, only a missing one is. This
+ // is deliberate, not an oversight: the alternative, --no-merge, wipes
+ // every hand translation in the bundle, not just the ones the schema
+ // changed. The maintenance path is a translator re-editing the leaf in
+ // place (the generated bundle header names it); nothing here or in
+ // `os i18n check` distinguishes that deliberate edit from a leaf
+ // nobody has looked at since the source moved.
  mergeExisting: !flags['no-merge'],
  });
 

diff --git a/packages/cli/src/utils/i18n-extract.ts b/packages/cli/src/utils/i18n-extract.ts
@@ -1173,6 +1173,12 @@ export function renderTranslationModule(
  `Auto-generated by 'os i18n extract' for locale '${options.locale}'.`,
  'Edit translations in place; re-run extract (with --merge) to fill new gaps.',
  'Do not hand-edit the structure — only the leaf string values.',
+ 'Merge only fills gaps: correcting a source label/description does not',
+ 'push the correction into a leaf here that already holds a translation —',
+ 'a present-but-stale string is not a gap, so it is left as-is. Re-translate',
+ 'it by hand when its source changes; nothing here or in `os i18n check`',
+ 'tells a leaf a translator updated on purpose from one nobody has looked',
+ 'at since the source moved.',
  ];
 
  const lines: string[] = [];

diff --git a/packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts b/packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'en'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/platform-objects/src/apps/translations/en.objects.generated.ts b/packages/platform-objects/src/apps/translations/en.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'en'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts b/packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'es-ES'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/platform-objects/src/apps/translations/es-ES.objects.generated.ts b/packages/platform-objects/src/apps/translations/es-ES.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'es-ES'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts b/packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'ja-JP'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/platform-objects/src/apps/translations/ja-JP.objects.generated.ts b/packages/platform-objects/src/apps/translations/ja-JP.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'ja-JP'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts b/packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'zh-CN'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/platform-objects/src/apps/translations/zh-CN.objects.generated.ts b/packages/platform-objects/src/apps/translations/zh-CN.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'zh-CN'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/plugins/plugin-approvals/src/translations/en.objects.generated.ts b/packages/plugins/plugin-approvals/src/translations/en.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'en'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/plugins/plugin-approvals/src/translations/es-ES.objects.generated.ts b/packages/plugins/plugin-approvals/src/translations/es-ES.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'es-ES'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/plugins/plugin-approvals/src/translations/ja-JP.objects.generated.ts b/packages/plugins/plugin-approvals/src/translations/ja-JP.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'ja-JP'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/plugins/plugin-approvals/src/translations/zh-CN.objects.generated.ts b/packages/plugins/plugin-approvals/src/translations/zh-CN.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'zh-CN'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/plugins/plugin-audit/src/translations/en.objects.generated.ts b/packages/plugins/plugin-audit/src/translations/en.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'en'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/plugins/plugin-audit/src/translations/es-ES.objects.generated.ts b/packages/plugins/plugin-audit/src/translations/es-ES.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'es-ES'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/plugins/plugin-audit/src/translations/ja-JP.objects.generated.ts b/packages/plugins/plugin-audit/src/translations/ja-JP.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'ja-JP'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/plugins/plugin-audit/src/translations/zh-CN.objects.generated.ts b/packages/plugins/plugin-audit/src/translations/zh-CN.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'zh-CN'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/plugins/plugin-security/src/translations/en.objects.generated.ts b/packages/plugins/plugin-security/src/translations/en.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'en'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/plugins/plugin-security/src/translations/es-ES.objects.generated.ts b/packages/plugins/plugin-security/src/translations/es-ES.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'es-ES'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/plugins/plugin-security/src/translations/ja-JP.objects.generated.ts b/packages/plugins/plugin-security/src/translations/ja-JP.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'ja-JP'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/plugins/plugin-security/src/translations/zh-CN.objects.generated.ts b/packages/plugins/plugin-security/src/translations/zh-CN.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'zh-CN'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/plugins/plugin-sharing/src/translations/en.objects.generated.ts b/packages/plugins/plugin-sharing/src/translations/en.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'en'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/plugins/plugin-sharing/src/translations/es-ES.objects.generated.ts b/packages/plugins/plugin-sharing/src/translations/es-ES.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'es-ES'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/plugins/plugin-sharing/src/translations/ja-JP.objects.generated.ts b/packages/plugins/plugin-sharing/src/translations/ja-JP.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'ja-JP'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';

diff --git a/packages/plugins/plugin-sharing/src/translations/zh-CN.objects.generated.ts b/packages/plugins/plugin-sharing/src/translations/zh-CN.objects.generated.ts
@@ -4,6 +4,12 @@
  * Auto-generated by 'os i18n extract' for locale 'zh-CN'.
  * Edit translations in place; re-run extract (with --merge) to fill new gaps.
  * Do not hand-edit the structure — only the leaf string values.
+ * Merge only fills gaps: correcting a source label/description does not
+ * push the correction into a leaf here that already holds a translation —
+ * a present-but-stale string is not a gap, so it is left as-is. Re-translate
+ * it by hand when its source changes; nothing here or in `os i18n check`
+ * tells a leaf a translator updated on purpose from one nobody has looked
+ * at since the source moved.
  */
 
 import type { TranslationData } from '@objectstack/spec/system';