Skip to content

Name the case where a catalog key holds a property name - #16

Merged
Jeehut merged 1 commit into
mainfrom
wip/migration-guide-property-keys
Oct 14, 2026
Merged

Jeehut merged 1 commit into
mainfrom
wip/migration-guide-property-keys

Conversation

@Jeehut

@Jeehut Jeehut commented Oct 14, 2026

Copy link
Copy Markdown
Member

What changes

MigrationGuide.md, section "The context part": one new bullet after "Properties contribute NOTHING". It names the case where a catalog key does contain the enclosing property name, and states that the catalog key wins.

Why

The removed macro (TranslationKey.semanticKey) did append property names when the compiler listed a VariableDeclSyntax in lexicalContext. Most toolchains never did, so the "properties contribute nothing" rule held for most catalogs, but not for all. A real migration of the TranslateKit app hit it: the same unchanged source produced two different key sets depending on when the catalog was extracted.

Evidence from the app's Localizable.xcstrings (catalog sync commit, Oct 2026), source unchanged in between – the call sits inside var userFriendlyMessage: String of BookmarkManager.BookmarkError:

-    "BookmarkManager.BookmarkError.theURLIsNotAValidFileURL" : {
+    "BookmarkManager.BookmarkError.UserFriendlyMessage.theURLIsNotAValidFileURL" : {

All six error keys in that property moved the same way. A migration that followed the derivation rule alone would have written the old form and orphaned all six translations; following "catalog first" gives the right key. The guide now says so explicitly instead of leaving it to luck.

Alternatives considered

  • Rewriting the rule to "properties contribute their name" – wrong for most existing catalogs; the derivation must stay as the default.
  • Leaving it to the "catalog first" rule – correct in principle, but the absolute "NOTHING" invites an agent to "fix" a catalog key that looks off. Naming the case closes that gap.

Proof

Docs-only change. Verified against the TranslateKit app: its migrated BookmarkManager.swift uses the UserFriendlyMessage keys verbatim, and all six messages showed as English text, none as raw keys, in a QA run of the app.

The guide said properties never contribute to a macro key. The macro
did append property names, but most compiler versions never passed the
enclosing property to it. A catalog extracted with a toolchain that did
holds keys such as
BookmarkManager.BookmarkError.UserFriendlyMessage.theURLIsNotAValidFileURL,
seen in a real app migration. The guide now names that case and says the
catalog key wins.
@Jeehut
Jeehut merged commit 51c8e74 into main Oct 14, 2026
1 check passed
@Jeehut
Jeehut deleted the wip/migration-guide-property-keys branch October 14, 2026 14:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant