@mmerterden/multi-agent-pipeline 11.1.0 → 11.3.0

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

@@ -1,393 +0,0 @@
-# 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).
-```