@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-2b-localization.md

@@ -0,0 +1,393 @@
+# PHASE 2B — Localization Keys
+
+Localization key integration for 8 languages (ar, de, en, es, fr, it, ru, tr).
+REF: `reference/localization-naming.md`
+
+Execute if visible text exists in the component.
+PARALLEL WITH: Phase 2A, Phase 2C (all read from pass1/_index.md independently)
+NEXT: Phase 2D (after all parallel phases complete)
+
+---
+
+## PRE-CHECK: Phase 1 Complete
+
+```
+Read: {artifactPath}/pass1/_index.md
+```
+
+Verify this file exists and lists the expected Phase 1 output files.
+
+Then read the files needed for this phase:
+- `{artifactPath}/pass1/design_context_response.json`
+- `{artifactPath}/pass1/component_properties.json`
+
+Also read:
+- `{artifactPath}/IMPLEMENTATION_HISTORY.md`
+
+Extract: `componentName`, `artifactPath`.
+
+### Registry Input (optional)
+
+The orchestrator may pass `registryData` containing pre-existing keys from `{repos.common.path}/Shared/Figma/Components/{nodeId}.json`.
+If `registryData.localizationKeys` exists and is non-empty, use it to pre-populate the keys list.
+Keys found in both registry AND the data files can be marked "Existing" immediately (skip CLI check in GATE 4).
+
+If any required file is missing:
+
+```
+STATUS: HALT
+PHASE: phase-2b
+GATE: PRE_CHECK
+REASON: Required Phase 1 artifacts missing. Pass1/_index.md or referenced files not found.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Run Phase 1 first to gather Figma data.
+```
+
+---
+
+## GATE 1: COLLECT_REQUIREMENTS
+
+| Priority | Source | Check |
+|----------|--------|-------|
+| 1 | User prompt | Explicit key requests |
+| 2 | Attached file | README.md, Confluence export, screenshot |
+| 3 | Generated | From design_context_response.json |
+
+USE: Merge all sources. User input overrides generated.
+
+---
+
+## GATE 2: EXTRACT_TEXTS_FROM_DESIGN_CONTEXT
+
+INPUT: `{artifactPath}/pass1/design_context_response.json`
+INPUT: `{artifactPath}/pass1/component_properties.json`
+
+SCAN for text content in `<p>` elements and text nodes.
+
+APPLY pattern detection:
+
+| Pattern | Detection | Action |
+|---------|-----------|--------|
+| Static text | Same text across variants | Single key, static value |
+| Dynamic placeholder | Single character varies (A, B, K, Y) | Format key with `%1$@` |
+| Repeated structure | `{Type}, {Class} Sınıfı` | Combined format key |
+| Domain-specific | Booking codes, cabin types | Deduce enum from context |
+
+### Domain Context Deduction
+
+| Domain | Pattern | Enum |
+|--------|---------|------|
+| Booking class | Single letter (K, Y, J, C, B...) | `BookingClassCode` |
+| Cabin class | Economy, Business | `CabinClass` |
+| Package type | Ecofly, Extrafly, Primefly... | `PackageType` |
+
+### Format Keys (dynamic parts)
+
+```
+Figma: "Ecofly, K Sınıfı" (K varies)
+Key: {ComponentName}.PackageWithClass
+Value (TR): %1$@, %2$@ Sınıfı
+Value (EN): %1$@, Class %2$@
+Runtime: String(format: key, "Ecofly", "K")
+```
+
+### Static Keys (fixed text)
+
+```
+Figma: "Yükseltildi"
+Key: {ComponentName}.Upgraded
+Value: Yükseltildi / Upgraded
+```
+
+### One key per unique pattern. Shared texts get single key.
+
+Also use `component_properties.json` to identify:
+- Text slots and their default values
+- Variant-dependent text changes
+
+OUTPUT: List of `{ key, value_tr, value_en, pattern }`.
+
+---
+
+## GATE 3: VALIDATE_NAMING
+
+REF: `reference/localization-naming.md`
+
+| Rule | Check |
+|------|-------|
+| Key format | PascalCase.Dot.Notation |
+| No unnecessary suffix | No `.Label`, `.Text`, `.Title` unless disambiguation needed |
+| Complete text | No runtime concatenation — display-ready strings |
+| Unique per pattern | One key per unique text pattern |
+| Shared texts | Single key for identical text across contexts |
+| Max 5 levels | Key hierarchy depth ≤ 5 |
+
+### Suffix Rules
+
+| Suffix Needed | Example |
+|---------------|---------|
+| Same element, different contexts | `{ComponentName}.Economy.Title`, `{ComponentName}.Economy.Description` |
+| Action vs display | `{ComponentName}.Submit.Button`, `{ComponentName}.Submit.Confirmation` |
+
+| No Suffix Needed | Example |
+|------------------|---------|
+| Single text per element | `{ComponentName}.Ecofly` |
+| Context clear from hierarchy | `{ComponentName}.Upgraded` |
+
+If any key fails validation, fix it before proceeding.
+
+---
+
+## GATE 4: CHECK_EXISTING_KEYS
+
+### Registry fast-path
+
+If `registryData.localizationKeys` contains this key, run the CLI check to confirm it still exists in the data file.
+If both registry AND CLI confirm → mark "Existing" immediately.
+If registry has it but CLI says not found → mark "To Add" (re-add it).
+
+### CLI check
+
+For each key in the list:
+
+```bash
+{repos.common.path}/.build/debug/TranslationManagerTool check --key '<KEY>' --config 'Shared/Localization/LocalizationStrings/localization-config.json'
+```
+
+OUTPUT:
+```
+✅ Key exists: <KEY>
+📊 Status:
+   Missing: 0
+```
+or
+```
+✅ Key exists: <KEY>
+📊 Status:
+   Missing: N
+```
+or
+```
+❌ Key not found: <KEY>
+```
+
+| Result | Action |
+|--------|--------|
+| `✅ Key exists` + `Missing: 0` | Mark status: "Existing" |
+| `✅ Key exists` + `Missing: N` | Mark status: "Incomplete" — needs missing language translations |
+| `❌ Key not found` | Mark status: "To Add" |
+
+FAIL (tool error) →
+```
+STATUS: HALT
+PHASE: phase-2b
+GATE: CHECK_EXISTING_KEYS
+REASON: TranslationManagerTool failed.
+COMPLETED_GATES: [PRE_CHECK, COLLECT_REQUIREMENTS, EXTRACT_TEXTS_FROM_DESIGN_CONTEXT, VALIDATE_NAMING]
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Options:
+  1) Retry command
+  2) Build tool first: swift build --package-path {repos.common.path} --product TranslationManagerTool
+  3) Skip localization integration
+```
+
+---
+
+## GATE 5: ADD_MISSING_KEYS
+
+**CRITICAL: Always use `TranslationManagerTool add` to add keys — NEVER edit localization JSON files directly. The tool writes to BOTH suggested and merged files atomically. Manual edits cause suggested/merged drift.**
+
+For each key with status "To Add" or "Incomplete":
+
+Translate to all 8 languages: ar, de, en, es, fr, it, ru, tr
+
+```bash
+{repos.common.path}/.build/debug/TranslationManagerTool add \
+  --key '<KEY>' \
+  --translations '{"en":"...","ar":"...","de":"...","es":"...","fr":"...","it":"...","ru":"...","tr":"..."}' \
+  --config 'Shared/Localization/LocalizationStrings/localization-config.json'
+```
+
+OUTPUT:
+```
+✅ Added/Updated: <KEY>
+```
+
+| Result | Action |
+|--------|--------|
+| All succeeded | Proceed to GATE 6 |
+| Any failed | HALT |
+
+FAIL →
+```
+STATUS: HALT
+PHASE: phase-2b
+GATE: ADD_MISSING_KEYS
+REASON: Failed to add localization key.
+COMPLETED_GATES: [PRE_CHECK, COLLECT_REQUIREMENTS, EXTRACT_TEXTS_FROM_DESIGN_CONTEXT, VALIDATE_NAMING, CHECK_EXISTING_KEYS]
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Options:
+  1) Retry failed command
+  2) Skip this key and continue
+  3) Skip localization integration entirely
+```
+
+---
+
+## GATE 6: REGENERATE_METADATA
+
+```bash
+{repos.common.path}/.build/debug/TranslationMetadataGenerator --config 'Shared/Localization/LocalizationStrings/localization-config.json'
+```
+
+OUTPUT:
+```
+✅ Metadata regenerated
+```
+
+| Result | Action |
+|--------|--------|
+| Succeeded | Proceed to GATE 7 |
+| Failed | HALT |
+
+FAIL →
+```
+STATUS: HALT
+PHASE: phase-2b
+GATE: REGENERATE_METADATA
+REASON: TranslationMetadataGenerator failed.
+COMPLETED_GATES: [PRE_CHECK, COLLECT_REQUIREMENTS, EXTRACT_TEXTS_FROM_DESIGN_CONTEXT, VALIDATE_NAMING, CHECK_EXISTING_KEYS, ADD_MISSING_KEYS]
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Options:
+  1) Retry command
+  2) Skip code generation (keys added but metadata not regenerated)
+```
+
+---
+
+## GATE 7: GENERATE_PLATFORM_CODE
+
+```bash
+cd {repos.packagesContainer}/{project.slug}-common && swift package plugin --allow-writing-to-package-directory generate-localization-code
+```
+
+OUTPUT:
+```
+✅ Generated iOS code
+```
+
+| Result | Action |
+|--------|--------|
+| Succeeded | Proceed to GATE 8 |
+| Failed | HALT |
+
+FAIL →
+```
+STATUS: HALT
+PHASE: phase-2b
+GATE: GENERATE_PLATFORM_CODE
+REASON: Code generation plugin failed.
+COMPLETED_GATES: [PRE_CHECK, COLLECT_REQUIREMENTS, EXTRACT_TEXTS_FROM_DESIGN_CONTEXT, VALIDATE_NAMING, CHECK_EXISTING_KEYS, ADD_MISSING_KEYS, REGENERATE_METADATA]
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Options:
+  1) Retry command
+  2) Skip code generation (keys added but not accessible in Swift code yet)
+```
+
+---
+
+## GATE 8: WRITE_ARTIFACT
+
+### JSON Sidecar (machine-readable)
+
+Write `{artifactPath}/pass2/utility_localization.json`:
+
+```json
+{
+  "localizationKeys": [
+    { "key": "ComponentName.KeyName", "pattern": "Static|Format" }
+  ]
+}
+```
+
+If no localization keys needed, write `{ "localizationKeys": [] }`.
+
+This JSON is consumed by `phase2-finalize.py` to build `component-utilities.json`. The orchestrator reads ONLY this JSON — never the markdown.
+
+### Markdown Artifact (human-readable)
+
+Write `{artifactPath}/pass2/utility_localization.md`:
+
+```markdown
+# Localization Keys
+
+Component: {componentName}
+Generated: {ISO_DATE}
+Source: pass1/design_context_response.json, pass1/component_properties.json
+Languages: ar, de, en, es, fr, it, ru, tr
+
+## Keys
+
+| Key | Pattern | Value (TR) | Value (EN) | Status |
+|-----|---------|-----------|------------|--------|
+| {ComponentName}.PackageWithClass | Format | %1$@, %2$@ Sınıfı | %1$@, Class %2$@ | Added |
+| {ComponentName}.Upgraded | Static | Yükseltildi | Upgraded | Existing |
+
+## Implementation
+
+```swift
+import LocalizationAssets
+
+// Static
+Text(LocalizationKey.{ComponentName}.upgraded.localized)
+
+// Format
+Text(String(format: LocalizationKey.{ComponentName}.packageWithClass.localized, packageName, classCode))
+```
+
+## Key Structure Reference
+
+| Type | Format | Example |
+|------|--------|---------|
+| Simple | Component.Element | {ComponentName}.Upgraded |
+| With variants | Component.VariantValue | {ComponentName}.Ecofly |
+| Nested | Component.Section.Element | {ComponentName}.Header.Title |
+| Disambiguation | Component.Element.Context | {ComponentName}.Date.Departure |
+```
+
+---
+
+## VALIDATION CHECKLIST
+
+Before marking complete, verify:
+
+```
+[ ] All visible text from design_context has localization keys
+[ ] Pattern detection applied: static vs dynamic vs format strings
+[ ] Key format: PascalCase.Dot.Notation
+[ ] No unnecessary suffixes (.Label, .Text unless needed)
+[ ] All 8 language translations provided (ar, de, en, es, fr, it, ru, tr)
+[ ] No runtime concatenation — display-ready strings only
+[ ] One key per unique text pattern
+[ ] TranslationManagerTool check passes for all keys
+[ ] TranslationMetadataGenerator completed
+[ ] generate-localization-code plugin completed
+[ ] utility_localization.json written to pass2/ (JSON sidecar for finalize script)
+[ ] utility_localization.md written to pass2/
+[ ] Implementation section shows correct import and usage patterns
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-2b
+GATES_PASSED: [PRE_CHECK, COLLECT_REQUIREMENTS, EXTRACT_TEXTS_FROM_DESIGN_CONTEXT, VALIDATE_NAMING, CHECK_EXISTING_KEYS, ADD_MISSING_KEYS, REGENERATE_METADATA, GENERATE_PLATFORM_CODE, WRITE_ARTIFACT]
+ARTIFACTS_CREATED:
+  - {artifactPath}/pass2/utility_localization.json
+  - {artifactPath}/pass2/utility_localization.md
+SUMMARY: Localization keys: {ADDED} added, {EXISTING} existing (8 languages each).
+```