Abdo-codes · MoElnaggar14 · Apr 30, 2026 · Jun 15, 2026 · Jun 15, 2026
diff --git a/README.md b/README.md
@@ -18,6 +18,7 @@ Included references:
 - `references/rtl-review.md` — Arabic/LTR visual audit and remediation flow
 - `references/apple-rtl-principles.md` — Apple-authored RTL rules and mirroring guidance
 - `references/copy-guidelines.md` — Arabic/English product copy and store copy rules
+- `references/parity-checker-examples.md` — examples for localization parity findings
 
 ## Install
 
@@ -59,9 +60,13 @@ cp -R apple-arabic-localization .agents/skills/
 iOS-dev-skills/
   apple-arabic-localization/
     SKILL.md                          # Skill definition (frontmatter + instructions)
+    scripts/
+      audit-localization.sh           # Static localization audit helper
+      check-localization-parity.py    # English/Arabic resource parity checker
     references/
       apple-localization-checklist.md # Implementation checklist
       rtl-review.md                   # RTL visual review guide
+      parity-checker-examples.md      # Example parity findings
       copy-guidelines.md              # Arabic/English copy rules
 ```
 
@@ -70,6 +75,7 @@ iOS-dev-skills/
 - "Localize this SwiftUI app to Arabic and English."
 - "Review all RTL issues in this iOS app."
 - "Run an English and Arabic RTL audit on this SwiftUI app."
+- "Check Arabic and English localization files for missing keys."
 - "Add in-app language switching for this Xcode project."
 - "Move all visible app strings into localization files."
 - "Prepare Arabic App Store copy for this app."

diff --git a/apple-arabic-localization/SKILL.md b/apple-arabic-localization/SKILL.md
@@ -14,10 +14,12 @@ This skill is for Xcode-based Apple apps only: SwiftUI, UIKit, app extensions, a
 ## Available Resources
 
 - `scripts/audit-localization.sh <repo-path>` — run first to find hard-coded locales, raw strings, notification copy, custom formatters, and RTL/LTR direction hotspots. Produces a structured report.
+- `scripts/check-localization-parity.py <repo-path>` — run after resource changes to compare English and Arabic `.strings`, `.stringsdict`, and `.xcstrings` keys, placeholders, empty values, untranslated values, and bidi risks.
 - `references/apple-localization-checklist.md` — end-to-end implementation checklist
 - `references/rtl-review.md` — Arabic/LTR visual audit, prioritization, and verification flow
 - `references/apple-rtl-principles.md` — Apple-authored RTL rules and what should or should not mirror
 - `references/copy-guidelines.md` — Arabic/English product copy and store copy rules
+- `references/parity-checker-examples.md` — examples of parity checker findings and how to interpret them
 
 ## When To Use
 
@@ -44,13 +46,16 @@ Do not use this skill for Android-only or web-only localization work.
 4. **Extract visible strings.**
    Move production-facing strings into the existing localization system (usually `Localizable.strings` or `.xcstrings`). Include views, reducers, notifications, seeded copy, errors, settings rows, and paywall/store messaging.
 
-5. **Wire the app root correctly.**
+5. **Check localization resource parity.**
+   Run `scripts/check-localization-parity.py <repo-path>` after changing localization resources. Fix missing keys and placeholder mismatches before visual review. Review warnings for untranslated Arabic, Arabic text in English resources, and Arabic strings that start with placeholders.
+
+6. **Wire the app root correctly.**
    Inject the active `Locale`, `Calendar`, and `layoutDirection` from the chosen language source. The root must react immediately to in-app language switches without requiring relaunch.
 
-6. **Refresh derived localized data on language change.**
+7. **Refresh derived localized data on language change.**
    Anything computed before the switch may need reload. Common misses: chart labels, seeded schedules, reminder text, cached summaries, tab labels created before the language changed.
 
-7. **Classify findings before fixing.**
+8. **Classify findings before fixing.**
    Split issues into:
    - shared primitives and design-system components
    - navigation and row affordances
@@ -59,7 +64,7 @@ Do not use this skill for Android-only or web-only localization work.
    - test coverage gaps
    Fix shared primitives first. Do not patch the same alignment bug independently across five screens if one shared row or field component is responsible.
 
-8. **Verify with focused tests and visual checks.**
+9. **Verify with focused tests and visual checks.**
    Add tests for formatting helpers, persistence, reducer actions, and reload behavior. Expand snapshot or visual coverage for both locales on the highest-traffic screens. Do final passes in both locales for navigation, sheets, forms, lists, tabs, progress bars, swipe actions, and dates/numbers.
 
 ## Gotchas

diff --git a/apple-arabic-localization/references/apple-localization-checklist.md b/apple-arabic-localization/references/apple-localization-checklist.md
@@ -16,6 +16,16 @@ Run `scripts/audit-localization.sh <repo-path>` first. It searches for:
 
 Review the audit output before proceeding. Then manually check for anything the script misses: reducer-generated text, cached summaries, and tab labels built at startup.
 
+Run `scripts/check-localization-parity.py <repo-path>` after editing localization resources. It checks English/Arabic resource parity for:
+
+- missing keys between English and Arabic
+- placeholder mismatches like `%@`, `%d`, `%f`, and `{name}`
+- empty Arabic values
+- Arabic values that still match English
+- English-looking Arabic values
+- Arabic text accidentally present in English resources
+- Arabic strings that start with placeholders and may need bidi isolation marks
+
 ## 2. Source Of Truth
 
 Create or reuse one language model that can answer:

diff --git a/apple-arabic-localization/references/parity-checker-examples.md b/apple-arabic-localization/references/parity-checker-examples.md
@@ -0,0 +1,83 @@
+# Localization Parity Checker Examples
+
+Use `scripts/check-localization-parity.py <repo-path>` after adding or changing Arabic and English localization resources.
+
+## Missing Arabic Key
+
+English:
+
+```text
+"settings.title" = "Settings";
+```
+
+Arabic:
+
+```text
+// key is missing
+```
+
+Expected finding:
+
+```text
+[error] en.lproj/Localizable.strings :: settings.title
+  Missing ar key
+```
+
+## Placeholder Mismatch
+
+English:
+
+```text
+"welcome.user" = "Welcome, %@";
+```
+
+Arabic:
+
+```text
+"welcome.user" = "مرحباً";
+```
+
+Expected finding:
+
+```text
+[error] en.lproj/Localizable.strings :: welcome.user
+  Placeholder mismatch: ['%@'] vs []
+```
+
+## Untranslated Arabic Value
+
+English:
+
+```text
+"paywall.restore" = "Restore Purchases";
+```
+
+Arabic:
+
+```text
+"paywall.restore" = "Restore Purchases";
+```
+
+Expected finding:
+
+```text
+[warning] en.lproj/Localizable.strings :: paywall.restore
+  ar value matches en
+```
+
+## Bidirectional Text Risk
+
+Arabic strings that start with placeholders can inherit the placeholder direction.
+
+Arabic:
+
+```text
+"activity.like" = "%@ أعجب بمنشورك";
+```
+
+Expected finding:
+
+```text
+[warning] en.lproj/Localizable.strings :: activity.like
+  Arabic value starts with a placeholder; review bidi isolation marks
+```