Text needs an architecture

1451. Lesson identity

Module

3.18 — Localization architecture

Lesson

Text needs an architecture

Academic type

Systems

Schema type

text

Order

1

Estimated time

30–45 minutes, including practice

1452. Learning objective

After this lesson, you can define a localization contract for one game feature by specifying stable keys, content ownership, fallback behavior, typed parameters, and locale-sensitive formatting boundaries.

1453. Why this matters

Localized text is product data, not a collection of replacement strings scattered through code. A feature becomes difficult to translate when its keys are unstable, its entries have no clear owner, or its formatting rules are mixed into content or callers. A clear contract also gives AI a constrained task: it can help generate or inspect entries without deciding the feature's language architecture for you.

1454. Prior knowledge

You should be able to describe data ownership and safe schema changes from Module 3.17, including the migration matrix from 3.17 L2 — Design a safe migration. You should also be able to distinguish a feature rule from its presentation and identify where a feature's data is read.

1455. Core concept

Localized content should be modeled as structured product data with an explicit contract.

A localization contract answers five questions:

1. Key: What stable semantic identifier does the feature use?
2. Ownership: Which feature or content domain maintains the entry?
3. Fallback: What happens when a requested locale or key is unavailable?
4. Parameters: Which named values does the caller provide, and what are their types?
5. Formatting policy: Which layer applies locale-sensitive rules for numbers, dates, times, units, currencies, and plural selection?

A key should describe the semantic intent of the text rather than its current wording. For example, delivery.confirmation.ready is more stable than your_order_is_ready, because it can survive a wording revision that still communicates readiness confirmation.

Stability does not mean that a key survives every content change. If an entry changes from a confirmation to a neutral status, warning, question, or error, its semantic intent may have changed. In that case, review the key. Create or rename the key when the old identifier would misrepresent the new meaning, and document how callers and localized entries migrate.

Ownership prevents duplicate or conflicting definitions. One feature or content domain should be responsible for maintaining an entry. Other systems request it through its key and parameters rather than silently substituting wording from another feature.

Fallback is a deliberate policy, not an accidental consequence of a failed lookup. A contract may specify a chain such as es-MX → es → en, followed by a visible missing-key marker. The exact chain can vary, but it must be observable and testable.

Parameters and formatting policy form a shared boundary. Callers should normally provide typed raw values, such as a destination identifier, integer quantity, date value, currency amount, or measurement. The localization or internationalization layer should apply locale-sensitive number, date, time, unit, currency, and plural rules. Callers should not normally pass preformatted locale-specific strings, because doing so can lock the value to the wrong locale or prevent correct plural selection.

The localized entry controls word order, punctuation, grammar, and placement of parameters. The caller owns the runtime value and its valid type. The formatting policy identifies which internationalization formatter transforms that typed value for the active locale.

1456. Mental model

Use the KEY → OWNER → FALLBACK → PARAMETERS → FORMAT POLICY model:

If a proposed entry cannot answer all five questions, its contract is incomplete.

1457. Concrete example

Suppose a delivery feature displays a confirmation when a package is ready at a destination.

A weak design might look like this:

show("Your package is ready at " + destinationName + ".")

This places English wording, concatenation, and sentence order in the caller. It also leaves fallback and formatting behavior unspecified.

A stronger contract is:

Key: delivery.confirmation.ready
Owner: delivery
Fallback: es-MX → es → en → [missing: delivery.confirmation.ready]
Parameters:
  destination: string
Formatting policy:
  localization entry owns word order, punctuation, and grammar
  caller supplies the raw destination value

English entry:

Your package is ready at {destination}.

Spanish entry:

Tu paquete está listo en {destination}.

A quantity-bearing message needs an additional policy:

Key: delivery.status.packagesReady
Parameters:
  packageCount: integer
Formatting policy:
  localization layer formats the number and selects the locale-appropriate plural form

The caller supplies an integer, not an English-formatted number or a preassembled phrase. Full formatter implementation is outside this lesson; the contract must still name the layer responsible for that work.

1458. Wording changes versus semantic changes

A wording-only revision preserves the message's communicative purpose. For example, changing “Your package is ready at {destination}” to “Your package is now ready at {destination}” still communicates a readiness confirmation, so delivery.confirmation.ready can remain appropriate.

A semantic change alters what the message does. Replacing that confirmation with “Package status: {destination}” may turn it into a neutral status label. Keeping delivery.confirmation.ready would then be misleading. The contract should require a semantic review, a new or renamed key when needed, and an explicit migration for callers and localized entries.

1459. Common mistakes

• Naming entries after screen position or current wording, such as button_text_2.
• Concatenating runtime values into translated sentences.
• Allowing each caller to invent its own fallback.
• Passing preformatted dates, currencies, quantities, or units without a documented reason.
• Assuming a stable key must remain unchanged after the message's semantic intent changes.
• Treating English as a neutral fallback without documenting regional, base-locale, and missing-key behavior.

1460. Guided practice

Create a localization contract for one small feature, such as a delivery confirmation, inventory warning, map destination label, or settings control. Define the architecture before writing a complete translation table.

Record these decisions:

1. Write three stable semantic keys. Avoid names based on screen position or current English wording.
2. Assign a responsible feature or content domain to each key.
3. Define a fallback chain for a regional locale, a base locale, and final missing-key behavior.
4. For one dynamic message, list each named parameter and its expected type.
5. Add a formatting policy. State that callers provide typed raw values and identify which layer applies locale-sensitive number, date, time, unit, currency, or plural rules that the message needs.
6. State what the localized entry controls and what remains runtime data.

Test the contract against two changes:

• Wording-only change: Revise “Your package is ready at {destination}” to “Your package is now ready at {destination}.” Explain why the semantic key can remain unchanged.
• Possible semantic change: Replace the confirmation with a neutral status message. Decide whether the original key still represents the message. If not, propose a new or renamed key and a migration for callers and localized entries.

1461. Validation and evidence

Submit the contract through the accompanying practical assessment. It must include three semantic keys, explicit ownership, fallback and missing-key behavior, typed parameters, a locale-sensitive formatting policy, and a decision record distinguishing wording changes from semantic changes.

The artifact is acceptable when another developer can determine where each entry belongs, what happens when it is missing, which typed values a caller may supply, which layer formats them, and when a content change requires a key migration.

1462. Key takeaways

• Localized text is structured product data with explicit ownership and behavior.
• Stable keys represent semantic intent rather than current wording or interface position.
• Wording changes can retain a key; meaning changes require semantic review and may require a new or renamed key plus migration.
• Fallback behavior must be ordered, observable, and testable.
• Callers should normally provide typed raw values; the localization or internationalization layer applies locale-sensitive formatting and plural rules.
• Localized entries control sentence structure, punctuation, grammar, and parameter placement.

1463. Knowledge check

1464. Next lesson

Continue to 3.18 L2 — Validate English and Spanish paths / Validar los recorridos en inglés y español using your keys, fallback chain, parameter types, formatting policy, and missing-key behavior as validation cases.

1465. Knowledge check