localship 0.1.0 → 0.3.0

package/skills/localship-extract/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: localship-extract
-description: Make an Android or iOS app localizable by moving text hardcoded in Kotlin, XML layouts or Swift into string resources or a String Catalog, without changing behavior. Use when an app has no translation files yet, when localship detect finds nothing, or when the user asks to find hardcoded strings.
+description: Make an Android or iOS app localizable by moving text hardcoded in Kotlin, XML layouts or Swift into string resources or a String Catalog, without changing behavior. Use when the user wants text ready for translation or hardcoded strings found, however they phrase it, and as the first step when they want the app in another language but its text is still in the code.
 ---
 
 # Make an app localizable
@@ -14,9 +14,8 @@ the rules below keep it safe. Change how text is looked up, never what the app d
 `localship detect` (or `localship_detect`) gives a first estimate: how much UI text is still in the
 code, per module, with examples. Use it to size the work, then search properly as below.
 
-Search the UI code for user-facing literals and show the user a summary grouped by screen or
-feature, with counts. Ask whether to do the whole app or one feature first. For big apps, go one
-feature at a time and build after each.
+Do the scope the user wants: the whole app unless they named particular screens or features. Search that code for user-facing literals, say in one line how
+much you found, and start. Build as you go, and give a short progress update after each part.
 
 **Android (Kotlin, Compose, Views)**, look for string literals in:
 - `Text("…")`, `text = "…"`, `label = { Text("…") }`, `title = "…"`, `placeholder`, `contentDescription = "…"`
@@ -32,59 +31,136 @@ feature at a time and build after each.
   `alert`/`confirmationDialog` text passed as `String`, `Button(title)` with a `String`
 - UIKit: `label.text = "…"`, `button.setTitle("…", for:)`, `title = "…"`
 - notification content, widget text, App Intents titles
+- default UI text in parameters (`title: String = "Cancel"`): not extracted until the parameter
+  is a `LocalizedStringResource` or the default is wrapped
+
+**Sentences built from English grammar** (both platforms). Wrapping these in a resource does
+nothing; search for them and rewrite each sentence whole:
+- pieces joined around a value (`"Finished " + amount + " over your plan."`, often so the value
+  can be styled): one complete sentence per case with placeholders, styling the value inside it
+  (`AttributedString(localized:)`; Android annotations or spans on the placeholder)
+- plural endings in code (`count == 1 ? "" : "s"`, `== 1 ?` near text): plural resources
+- helpers that spell out numbers, write ordinals or choose "a"/"an" (names with `spell`,
+  `ordinal`, `article`): formatters (`.formatted(.number.notation(.spellOut))`, an ordinal
+  `NumberFormatter`; ICU `RuleBasedNumberFormat` and `MessageFormat` on Android) or one sentence
+  per case
+- text surgery on UI strings (`replacingOccurrences`, `replace`, `removePrefix`): store both forms
+- lists (`joined(separator: ", ")` plus "and"): `.formatted(.list(type: .and))`,
+  `ListFormatter`, or ICU `ListFormatter` on Android
+
+Rewrite even when it adds variants, and keep the English output identical so tests still pass.
 
 **Leave alone:** log messages, analytics event names, preference and database keys, routes and
 deep links, test tags and accessibility identifiers, URLs, format patterns, debug-only screens,
-and anything never shown to users. Brand names can stay in code, or become resources marked
-not translatable.
+and anything never shown to users. Also text that doubles as data: enum raw values, `case`
+patterns, query item names, dictionary keys, and any string that's parsed back, compared or saved
+(picker values parsed into intervals, values written to export files). To show those translated,
+add a separate display property and keep the stored value as it is. Brand names can stay in code,
+or become resources marked not translatable.
 
 ## 2. Android rules
 
 - Put strings in `res/values/strings.xml` of the module that uses them. Create the file if needed:
   `<?xml version="1.0" encoding="utf-8"?>` then `<resources>…</resources>`.
-- Key names: `screen_role` in snake_case (`budget_title`, `budget_save_button`). Reuse an existing
-  key when the text *and* meaning are the same; otherwise make a new one.
-- Add a comment above each string saying where it appears and what placeholders mean:
-  `<!-- Budget screen: button that saves the plan. %1$s is the month name -->`
+  Keep a default for every resource the app uses; a definition only in `values-en` is not a default.
+  Check the merged resources with Android lint for the relevant build variants, especially when
+  libraries, flavors or multiple source sets supply defaults.
+- Key names and comments: follow the project's existing resources. If there are none, use
+  `screen_role` in snake_case (`settings_title`, `settings_save_button`) with a comment above each
+  string saying where it appears and what placeholders mean
+  (`<!-- Settings screen: saves changes. %1$s is the profile name -->`), and say so in your report.
+  Reuse an existing key when the text *and* meaning are the same; otherwise make a new one.
 - Escape `'` as `\'` and `"` as `\"`; `&` as `&amp;`.
 - **Never concatenate** text: one string with numbered placeholders (`%1$s`, `%2$d`) per sentence,
   so translators can reorder.
 - **Counts use plurals:** `<plurals name="…"><item quantity="one">%d item</item><item quantity="other">%d items</item></plurals>`.
 - Compose: `stringResource(R.string.key)`, `stringResource(R.string.key, arg)`,
   `pluralStringResource(R.plurals.key, count, count)`.
-- Outside composables: `context.getString(…)` / `resources.getQuantityString(…)`. Don't pass a
-  `Context` into a ViewModel: expose `@StringRes` ids, or a small `UiText` wrapper resolved in the UI.
+- Outside composables: `context.getString(…)` / `resources.getQuantityString(…)`. For text built
+  in view models or other non-UI code, follow the pattern the project already uses. If it has
+  none, expose `@StringRes` ids or a small `UiText` wrapper resolved in the UI rather than passing
+  a `Context`, and say so in your report.
 - Money, numbers and dates go through formatters (`NumberFormat`, `DateTimeFormatter.ofLocalizedDate`),
-  never hand-built strings.
+  never hand-built strings. Keep the amount signed and set its actual currency; changing the display
+  language must not change the currency. Respect the user's regional and numbering preferences.
 - Brand names that must not change: `<string name="app_name" translatable="false">…</string>`.
+- Check `android:supportsRtl`, start/end spacing and alignment, and directional icons. Mirror
+  directional navigation affordances when appropriate; do not mirror every image or chart blindly.
+- Localship handles plain locale folders. Qualified string resources such as `values-ar-night`
+  remain separate; a coverage warning must be resolved with platform checks, not by moving those
+  strings into a plain locale folder or removing the qualifiers.
 
 ## 3. iOS rules
 
-- A String Catalog must exist. If there is none, ask the user to add one in Xcode
-  (File › New › File from Template › String Catalog, named `Localizable`) or create
-  `Localizable.xcstrings` in the app target's folder containing
-  `{"sourceLanguage" : "en", "strings" : {}, "version" : "1.0"}`. In Xcode 16 synced folders it
-  is picked up automatically; otherwise it must be added to the target in Xcode.
+- **Generated projects:** when `project.yml` (XcodeGen) or `Project.swift` (Tuist) exists, make
+  every project change there and regenerate; never edit the `.pbxproj` or rely on changes made in
+  Xcode, which regeneration drops. In XcodeGen that's `options: developmentLanguage: <lang>` and,
+  under `settings: base:`, `SWIFT_EMIT_LOC_STRINGS: YES` and
+  `LOCALIZATION_PREFERS_STRING_CATALOGS: YES`, with each catalog inside a source folder of its
+  target.
+- Every target that shows text (the app, widgets and other extensions) needs its own catalog in
+  its sources.
+- Use String Catalogs and the project's actual development language; never assume English.
+  Reuse existing tables. For a new catalog, use Xcode's localization preparation tools when
+  available, or create `Localizable.xcstrings` in the appropriate target with `sourceLanguage`
+  matching the development language, an empty `strings` object and `version: "1.0"`.
+  Verify target membership and resource inclusion, including extensions and Swift packages.
+- Verify **Use Compiler to Extract Swift Strings** (`SWIFT_EMIT_LOC_STRINGS`) for the relevant
+  targets. Build all relevant schemes/targets and supported platforms before translating;
+  building only the main app may miss platform-conditional strings and extension resources.
+- **Filling the catalog:** a command-line build (`xcodebuild`) writes `.stringsdata` files into
+  DerivedData but leaves the `.xcstrings` unchanged; only Xcode's catalog editor merges them. An
+  empty catalog after a clean build doesn't mean extraction failed. Sync each catalog from its
+  own target's build output:
+  ```sh
+  xcrun xcstringstool sync <Target>/Localizable.xcstrings \
+    --stringsdata <DerivedData>/Build/Intermediates.noindex/<Project>.build/<Config>-<sdk>/<Target>.build/Objects-normal/*/*.stringsdata
+  ```
+- **Keys with no words** (`" "`, `"·"`, `"%@%@"`, `"—"`) come from text built in pieces.
+  Localship skips them; mark them `"shouldTranslate" : false` in the catalog so Xcode's progress
+  agrees, and check whether each one is a sentence split into pieces that should be rewritten.
+- For copy-heavy models (personalities, tips, onboarding pages), changing an initializer
+  parameter from `String` to `LocalizedStringResource` extracts all the copy passed to it.
 - `Text("literal")`, `Button("literal")`, `Label("literal", …)` are extracted by Xcode
-  automatically. Add a comment where the meaning isn't obvious: `Text("Save", comment: "Saves the budget")`.
-- Text in variables: make it `String(localized: "…", comment: "…")` where it's created, or type the
-  property as `LocalizedStringResource` / `LocalizedStringKey`.
+  automatically. Add a comment where the meaning isn't obvious: `Text("Save", comment: "Saves the profile")`.
+- Prefer `LocalizedStringResource` for passing localizable text through models and custom views;
+  use `String(localized:)` where a resolved string is needed. Avoid caching resolved translations
+  across language changes. `LocalizedStringKey` also works for SwiftUI-specific view APIs.
+- Specify the right table and bundle for non-default catalogs, frameworks and packages.
+  On toolchains supporting it, `#bundle` refers to the current target's resources; otherwise use
+  the appropriate bundle, such as `Bundle.module` in a Swift package, rather than assuming `.main`.
+- Xcode 26+ can generate typed `LocalizedStringResource` symbols for manually managed keys;
+  respect an existing symbol-based workflow. It also offers automatic translator comments;
+  review generated comments and add app-specific meaning and placeholder context.
 - Use `Text(verbatim:)` for text that must never be translated (codes, user content).
 - Interpolations become placeholders automatically: `Text("\(count) items")` → key `%lld items`.
-  Counts need plural forms: list those strings and tell the user to right-click them in the
-  catalog › Vary by Plural, since that's done in Xcode.
+  Counts need plural forms: after syncing, find the keys with count placeholders (`%lld`,
+  `%d`) and give them plural variations (**Vary by Plural** in Xcode, or `variations.plural` in
+  the catalog JSON with the forms the source language needs). Whatever you can't convert, list
+  in your report so the user can do it in Xcode before translating.
+  Multiple independent counts require substitutions; device wording may require device variants.
+  Localship cannot translate or validate those advanced entries yet. Keep their structure and
+  use Xcode to handle them; never flatten them to make Localship's checks pass.
 - Money, numbers and dates: `.formatted()` and `FormatStyle`, never hand-built strings.
-- **Build once** (in Xcode, or `xcodebuild … build`) so Xcode collects the strings into the catalog.
+- Include user-facing permission descriptions and other localizable Info.plist values through
+  `InfoPlist.xcstrings`, plus storyboard/xib and App Intents text where the app uses them.
+- Xcode 27 has native agent localization and preview tools. When available, use them for project
+  preparation and visual review, keeping the same glossary and voice guidance. If they edit
+  translations tracked by Localship, review the resulting hand edits before adopting them.
 
 ## 4. Check nothing was missed
 
-- The app must build after each chunk. Don't change logic, layout or behavior.
+- The app must build after each chunk. Don't change logic, layout or behavior. Run Android lint
+  for affected variants, or build the affected Apple targets/platforms; file validation alone
+  cannot verify resource merging, extraction or runtime lookups.
 - Android: enable pseudolocales (`android { buildTypes { debug { isPseudoLocalesEnabled = true } } }`),
   switch the device to "English (XA)", and look for text that isn't accented: that text is still hardcoded.
   "AR (XB)" shows right-to-left layout problems.
 - iOS: Scheme › Run › Options › App Language › "Accented Pseudolanguage" (and "Right-to-Left
-  Pseudolanguage"). Plain English left over was missed.
-- Ask the user to run these if you can't; list the screens to check.
+  Pseudolanguage"). Plain English left over was missed. Without Xcode's UI, a scripted check works:
+  add a temporary language whose values wrap the English in markers (`⟦Save⟧`), launch with
+  `-AppleLanguages "(xx)"`, look for text without markers, then remove the temporary language.
+- If you can't run these, list the screens for the user to check.
 
 ### Text the resource files can't show
 
@@ -94,21 +170,29 @@ for them while you're in it:
 - **Names stored in data.** Categories, accounts or templates seeded in English and saved to a
   database are shown as stored. Translate them at display time while they're still the seeded
   value (a map from seeded name to string resource); never translate what the user typed.
+  Use the translated name only for showing it: anything saved (database rows, defaults,
+  exports, a name copied into a new record) keeps the stored value, or it stays in whatever
+  language the app had when it was saved.
 - **Text built once and kept.** View models, singletons and caches that build sentences keep the
   old language after an in-app language switch. Rebuild them when the locale changes; on Android,
   view models survive the activity being recreated for the new language.
-- **Charts drawn by hand.** A Canvas or custom drawing doesn't mirror in right-to-left languages,
-  but the labels laid out next to it do, so the bars end up under the wrong labels. Mirror the
-  drawing when the layout direction is right to left.
-- **Signs and symbols on amounts.** `"-" + amount` comes out as `$60-` in Arabic. Keep a signed
-  amount in one left-to-right run (wrap it in U+2066 … U+2069). Android's Arabic number
-  format also starts with an invisible right-to-left mark (U+200F), which can cut the symbol
-  off single-line figures; strip it.
-- **Dates and months** formatted with the device's locale instead of the app's: use the app's
-  locale so they follow an in-app language switch.
+- **Charts drawn by hand.** Check that custom drawing and surrounding labels agree in RTL.
+  Decide mirroring based on the chart's meaning and axis conventions, and test it on a device.
+- **Signs and symbols on amounts.** Format the signed value as one unit with the platform's
+  number/currency formatter. Preserve its Unicode direction marks. Do not prepend a minus sign,
+  strip U+200F or force every amount to LTR. For dynamic text inserted into an Android localized
+  message, use context-aware `BidiFormatter.unicodeWrap()` unless already wrapped. On Apple,
+  use localized interpolation and natural text direction. Test positive/negative amounts,
+  currency symbols and mixed-script text in the actual UI before adjusting directionality.
+- **Dates and months.** Check that language switching refreshes labels while formatters respect
+  intended regional preferences; language, region, calendar and currency are separate choices.
+
+Use the [platform verification guide](references/platform-localization.md) for current official
+references and the final test checklist.
 
 ## 5. Then
 
-Run `localship detect` (or `localship_detect`): it should now find the strings. Continue with the
-`localship-setup` skill. Commit nothing unless the user asks; suggest committing the extraction on its
-own before translating, so the diff is easy to review.
+Run `localship detect` (or `localship_detect`): it should now find the strings. Report what you
+moved, and any convention you had to pick. If the user also asked for translation, continue with
+the `localship` skill. Don't create branches or commit unless the user asks; if they do commit,
+suggest committing the extraction on its own, so the diff is easy to review.

package/skills/localship-extract/references/platform-localization.md

@@ -0,0 +1,65 @@
+# Platform verification
+
+Guidance checked against official Android and Apple documentation on October 17, 2026.
+Check the project's installed toolchain and deployment targets before applying newer APIs.
+
+## Android
+
+- Keep all needed default strings in unqualified `values` resources. Verify resource merging
+  and references with the relevant Gradle lint/build tasks. A Localship target is a resource
+  directory, not a model of every dependency, flavor and source set in the APK.
+- Plain locale folders are supported. Strings in other configurations are preserved and reported
+  as uncovered; `--strict` and `--require-approved` fail for those files. Do not remove qualifiers
+  or copy conditional overrides into base resources to silence this diagnostic.
+- Test supported languages with the system and any in-app picker, including persistence and
+  switching while screens and view models remain alive.
+- Format signed currency values using their actual currency and the intended display locale.
+  Preserve direction marks produced by formatters; use bidi-aware handling for embedded text.
+
+Official references:
+
+- [Localization and default resources](https://developer.android.com/guide/topics/resources/localization)
+- [String resources and plurals](https://developer.android.com/guide/topics/resources/string-resource)
+- [Per-app language setup and migration](https://developer.android.com/guide/topics/resources/app-languages)
+- [RTL, layout mirroring and BidiFormatter](https://developer.android.com/training/basics/supporting-devices/languages)
+- [Pseudolocales](https://developer.android.com/guide/topics/resources/pseudolocales)
+
+## Apple platforms
+
+- Use the actual development language, correct table/bundle, and compiler extraction. Build
+  relevant targets and platforms before treating catalogs as complete; include extensions,
+  packages, Info.plist text and interface resources used by the app.
+- Command-line builds write `.stringsdata` but don't update catalogs; sync them with
+  `xcrun xcstringstool sync`. In XcodeGen or Tuist projects, make localization settings in
+  `project.yml` or `Project.swift`, since regenerating drops changes made in Xcode.
+- Keep device variants and substitutions intact. Localship currently models plain strings and
+  one level of plural string units. Advanced entries remain in the catalog but block strict
+  completeness checks. Handle them in Xcode and report that Localship cannot certify the whole
+  catalog; do not set `shouldTranslate: false` merely to bypass validation.
+- Generated symbols are optional: preserve the project's chosen extraction/manual-key workflow.
+  Review generated comments for accurate context. Native Xcode agent tools can prepare catalogs
+  and preview translations; align them with the project's terminology and review their edits.
+
+Official references:
+
+- [String Catalogs, plurals and device variants](https://developer.apple.com/documentation/Xcode/localizing-and-varying-text-with-a-string-catalog)
+- [Compiler extraction, bundles and substitutions](https://developer.apple.com/videos/play/wwdc2023/10155/)
+- [Xcode 26 comments, symbols and resource bundles](https://developer.apple.com/videos/play/wwdc2025/225/)
+- [Generated localizable symbols](https://developer.apple.com/documentation/xcode/using-generated-localizable-symbols-in-your-code)
+- [Xcode 27 agent localization and visual review](https://developer.apple.com/videos/play/wwdc2026/213/)
+
+## Release verification
+
+1. Run Localship validation; review errors, warnings and coverage gaps. After approving the
+   selected locales, run `localship validate --require-approved --locale <locales>`.
+2. Run the native build and applicable Android lint tasks. Resolve missing defaults and wrong
+   target/bundle membership. File validation cannot replace these checks.
+3. Exercise pseudolocales and actual languages: long text, tall scripts, RTL and large system
+   text sizes. Look for clipping, incorrect alignment, inaccessible labels and layout changes.
+4. Check plural boundaries appropriate to each locale, signed/zero amounts, mixed-script names,
+   and date/calendar/number formatting. Preserve user-entered content.
+5. Test language switching, navigation, notifications, widgets and cached/seeded labels where
+   the app has them. Get native-speaker feedback on meaning and tone.
+
+Report which checks ran and which could not. Approval records do not prove linguistic quality,
+and a passing check for supported files does not establish correct runtime behavior.

package/skills/localship-review/SKILL.md

@@ -23,7 +23,8 @@ installed, ask to install it once with `npm install -g localship`.
    localship next-batch --locale hi --states draft
    ```
    Each item shows `source` and the translation as `current`, with the comment, plural forms
-   and glossary. Read `.localship/brief.md` and the locale's voice first.
+   and glossary. A `note` says how the translator read an ambiguous source: check that reading
+   first, and mention it to the user if you're not sure. `role` says where it appears. Read `.localship/brief.md` and the locale's voice first.
    To review translations made before Localship, use `--states untracked`; for hand edits,
    `--states edited`. Fixing those replaces a person's work, so ask before resubmitting, and
    pass `--force` only then.
@@ -49,4 +50,12 @@ installed, ask to install it once with `npm install -g localship`.
    - `--from edited` accepts hand edits; `--from untracked` adopts translations made before
      the tool.
 
-Run `localship validate` at the end; it must have no errors. Commit nothing unless asked.
+Run `localship validate` at the end; it must have no errors. Report coverage warnings separately:
+unsupported variants are not reviewed just because the supported entries passed. After approval,
+use `localship validate --require-approved --locale <reviewed-locales>` for the release check.
+Do not auto-approve or flatten unsupported entries to satisfy that check.
+
+For a release, follow the [platform verification checklist](../localship-extract/references/platform-localization.md):
+native build/lint, pseudolocales, large text, RTL, language switching and native-speaker review.
+Use Xcode preview tools when available for visual checks, and report what still needs a device.
+Commit nothing unless asked.

package/skills/localship-setup/SKILL.md

@@ -9,8 +9,8 @@ Localship keeps translations in the repo's own files (Android `res/values-*/stri
 gettext `.po`, Apple `.xcstrings`) and checks every translation in code. You do the parts
 that need judgment: choosing what to set up, and writing the context translators use.
 
-> For a direct request ("translate this app to Hindi"), start with the `localship` skill: it
-> plans once, asks for one confirmation, and then uses this playbook without more questions.
+> For a direct request ("translate this app to Hindi"), start with the `localship` skill instead:
+> it sets up only the config and translates.
 
 ## Running the tool
 
@@ -19,9 +19,6 @@ that need judgment: choosing what to set up, and writing the context translators
   `npm install -g localship` (running it through `npx` every time is slow).
 - Add `--json` when you need to read the output.
 
-Before writing anything, check `git status`. If there are uncommitted changes, mention it, so the
-user can tell your changes apart from theirs.
-
 ## 1. Find out where the project stands
 
 Run `localship status`. If it works, the project is already set up (if it warns that most text is still in the code, go to case C): go to step 5 (context) if
@@ -30,20 +27,19 @@ pick the case that fits:
 
 | What detect shows | Case |
 |---|---|
-| A warning that most of the app's text is still in the code (more UI text in code than strings in resources) | **C. Text is hardcoded**, even if a few strings exist: run `localship-extract` first, or translations will cover only part of the app. Tell the user how much is in code |
+| A warning that most of the app's text is still in the code (more UI text in code than strings in resources) | **C. Text is hardcoded**, even if a few strings exist: tell the user how much is in code; translations cover only what's in resources until it's moved (the `localship-extract` skill, if they ask) |
 | Setups with existing languages (`hi, ar` …) | **A. Already localized** |
 | Setups with strings but no languages | **B. Ready to translate** |
-| An empty String Catalog (0 strings) | Ask the user to build the app in Xcode once, then detect again |
+| An empty String Catalog (0 strings) | Check compiler extraction and target membership, build the relevant targets and platforms, and sync the catalog from the build (`xcrun xcstringstool sync`; a command-line build alone leaves it empty, see `localship-extract`), then detect again |
 | A gettext template with no translations | **B**, after confirming where new `.po` files go (detect suggests a path) |
-| Nothing, with a hint about Android or Xcode | **C. Text is hardcoded**: run the `localship-extract` skill first, then come back |
+| Nothing, with a hint about Android or Xcode | **C. Text is hardcoded**: nothing to set up until the text is in resources; the `localship-extract` skill moves it, if the user asks |
 | Only formats listed as "not supported yet" (Flutter ARB, JSON, `.strings` …) | Say so plainly; Localship can't translate those yet |
 
-## 2. Ask, then init
+## 2. Init
 
-Show the user what was found and ask:
-- which setups to include (skip debug, test and sample folders unless they want them);
-- **case A:** whether to keep translating the languages already there, and whether to add more;
-- **case B:** which languages to translate into. Suggest from their market if they don't know.
+Include every setup detect found except debug, test and sample folders, unless the user said
+otherwise. Languages: the ones the user named, plus (case A) the ones already there. If the user
+named none and there are none, ask which; that's the one thing setup can't guess.
 
 Then run `localship init --accept <numbers> --locales <list>` (add `--source <locale>` if the detected
 source language is wrong). Language codes are BCP 47 (`hi`, `ar`, `pt-BR`, `zh-Hans`). Never pass
@@ -51,40 +47,57 @@ source language is wrong). Language codes are BCP 47 (`hi`, `ar`, `pt-BR`, `zh-H
 
 ## 3. Existing translations (case A)
 
-They show as `untracked`: made before Localship, so the tool doesn't know if they're good. Ask:
-- **Trust them:** `localship approve --from untracked`.
-- **Review first:** run the `localship-review` skill on them (it can fetch untracked strings).
-- **Leave them:** they stay as they are and are never overwritten without the user's say-so.
-Then `localship validate`: existing files often have real problems (missing placeholders, broken
-plurals). Report the errors and offer to fix them.
+They show as `untracked`: made before Localship, so the tool doesn't know if they're good. Leave
+them as they are; they're never overwritten without the user's say-so. In your report, mention
+that the user can approve them (`localship approve --from untracked`) or have them reviewed (the
+`localship-review` skill). Run `localship validate`: existing files often have real problems
+(missing placeholders, broken plurals). Report the errors; fix them if the user asks.
 
 ## 4. Platform setup the tool can't do (mention what applies)
 
-- Android: per-app language picker — in `build.gradle(.kts)` set
-  `androidResources { generateLocaleConfig = true }` and add
-  `app/src/main/res/resources.properties` with `unqualifiedResLocale=en-US` (the source).
-- iOS: add each language under Project › Info › Localizations so Xcode keeps them.
+- Android: inspect AGP, compileSdk and any existing language configuration first. Automatic
+  `androidResources { generateLocaleConfig = true }` needs AGP 8.1+ and compileSdk 33+.
+  Set `unqualifiedResLocale` in the app module's `res/resources.properties` to the actual
+  default locale, not an assumed `en-US`. Do not combine a manual LocaleConfig with generation;
+  reconcile the existing setup. Check the generated supported-language list, including library
+  resources, and restrict it to languages ready for release using the installed AGP's supported
+  locale-filter configuration.
+- Android in-app selection: integrate platform `LocaleManager` on Android 13+ or compatible
+  AndroidX `AppCompatDelegate.setApplicationLocales`; consider the Activity/context requirements
+  on older devices, persisted preferences and migration from any existing picker. Test system
+  settings, app settings, restart and configuration changes together. Generating LocaleConfig
+  alone does not implement a backward-compatible picker.
+- iOS: add languages through the catalog/project localization settings or available Xcode
+  preparation tools. Check the development language, resource bundles, compiler extraction and
+  all relevant targets/platforms, as described in `localship-extract`. Xcode 27's native agent
+  tools can assist preparation; use them when available, with the project's glossary and voice.
+
+Read [platform verification](../localship-extract/references/platform-localization.md) for the
+official references. Report unsupported catalog/resource configurations before translating;
+strict validation blocks them even when supported strings are all complete.
 
 ## 5. Write the context
 
-Create these in `.localship/` (the `context` folder in the config). Draft them from the README, store
-listing, website copy and the strings themselves, then show the user and adjust.
+The user asked for setup, so write these in `.localship/` (the `context` folder in the config).
+Draft them from the README, store listing, website copy and the strings themselves, and show the
+user what you wrote. Don't overwrite files that already exist.
 
 - `brief.md`: what the app does, who uses it, the tone of its copy (calm, playful, formal…), and
-  anything translators get wrong without context (e.g. "a 'budget' is a monthly spending plan,
-  not a cheap option"). Half a page at most.
+  anything translators get wrong without context (e.g. "a 'notebook' is a group of notes, not
+  a paper notebook"). Half a page at most.
 - `voice/all.md`: voice rules for every language. `voice/<locale>.md`: per language, e.g. formality
-  (German du vs Sie, Hindi तुम vs आप), English loanwords, number and date conventions. Ask the user
-  their preference for formality; don't guess silently.
+  (German du vs Sie, Hindi तुम vs आप), English loanwords, number and date conventions. Use what the
+  user said; otherwise the usual convention for consumer apps in that language, and name the choice
+  in your summary so they can change it.
 - `glossary.yaml`: brand and product names to keep (`translate: false`), and product terms that
   must be translated consistently:
   ```yaml
   terms:
-    - term: StillMoney
+    - term: Jotter
       translate: false
-    - term: safe to spend
-      note: The amount the user can spend today without breaking their budget
-      translations: { hi: खर्च के लिए सुरक्षित }
+    - term: notebook
+      note: A named group of notes, not a paper notebook
+      translations: { hi: नोटबुक }
   ```
   Keep it short: names, and terms that appear in many strings or carry product meaning.
 
@@ -93,7 +106,8 @@ Without file access, use `localship_update_context` instead.
 ## Cleaning up
 
 After strings are deleted or renamed, `localship prune --dry-run` shows leftover translations; show
-the user, then run `localship prune`.
+the user, then run `localship prune`. First verify that the source keys were actually removed:
+a missing Android default can look like a leftover translation, and should be restored instead.
 
 ## Adding languages later
 
@@ -101,5 +115,5 @@ the user, then run `localship prune`.
 
 ## Finish
 
-Run `localship validate` and `localship status`, and tell the user the next step: the `localship-translate` skill
-(or `localship translate --model …` for a large catalog). Commit nothing unless the user asks.
+Run `localship validate` and `localship status`, and tell the user the next step: translating (the
+`localship-translate` skill). Commit nothing unless the user asks.

package/skills/localship-translate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: localship-translate
-description: Translate an app's missing or changed strings with Localship — fetch batches with context, translate them, submit them for checks, and fix what's rejected until nothing is left. Use when the user asks to translate, localize, add a language, or update translations after copy changes.
+description: Translate an app's missing or changed strings with Localship — fetch batches with context, translate them, submit them for checks, and fix what's rejected until nothing is left. Use for the translating itself, once the text is in string resources; for a request to localize the app or add a language, start with the localship skill, which works out whether text has to be moved first.
 ---
 
 # Translate with Localship
@@ -10,7 +10,7 @@ The tool picks the strings, gives you the context, checks every translation in c
 You translate. Don't edit translation files by hand.
 
 > For a direct request ("translate this app to Hindi"), start with the `localship` skill: it
-> plans once, asks for one confirmation, and then uses this playbook without more questions.
+> checks the project, then uses this playbook.
 
 ## Running the tool
 
@@ -19,23 +19,23 @@ You translate. Don't edit translation files by hand.
   `npm install -g localship`.
 - No `.localship/config.yaml`? Run the `localship-setup` skill first.
 - A language that isn't configured yet: `localship add-locale <code>` first.
-- Check `git status` first and mention uncommitted changes, so the translation diff stays reviewable.
 
 ## 1. Size up the work
 
 Run `localship status`. Count `missing` + `stale` across the locales to translate.
+Read the status notes too. Unsupported Apple variations and Android configurations are excluded
+from the counts; report them as uncovered work and preserve their structure. Zero remaining
+batch entries does not mean those strings have been translated or validated.
 
-- **Up to a few hundred strings:** translate them yourself (step 2).
-- **More than that**, or the user wants it done without you: delegate to a model API with
-  `localship translate --model <provider:model>` (or `models:` in the config). Providers:
-  `anthropic`, `openai`, `gemini`, `openrouter` (keys from `ANTHROPIC_API_KEY`,
-  `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`), and local `ollama`, `lmstudio`.
-  It runs the same checks and retries rejected strings. Then review what it reports as failed
-  and translate those yourself.
+Translate them yourself (step 2), however many there are. Use a model API
+(`localship translate --model <provider:model>`) only when the user asks for it: cloud providers
+(`anthropic`, `openai`, `gemini`, `openrouter`) bill per use and need their API key; local
+`ollama` and `lmstudio` are free. It runs the same checks; translate what it reports as failed
+yourself.
 
-Read `.localship/brief.md`, `.localship/voice/` and `.localship/glossary.yaml` once if they exist. If
-there's no brief, write a short one first (see `localship-setup`): translations without context
-come out generic.
+Read `.localship/brief.md`, `.localship/voice/` and `.localship/glossary.yaml` once if they exist.
+If there's no brief, read the README for what the app does and its tone; don't write a brief
+unless the user asks.
 
 ## 2. The loop
 
@@ -51,7 +51,8 @@ come out generic.
    - `editedByHand: true` — a person edited the current translation. Keep their wording where you
      can, and show the user your proposed change: `submit` refuses it until they agree (then pass
      `--force` for just those strings).
-   The batch also carries the `brief`, each locale's `voice`, and notes per format.
+   The batch also carries the `brief`, each locale's `voice` (or `defaultVoice`, the usual
+   convention, when the project has set none), and notes per format.
 
 2. Translate every item following these rules:
    - Natural, concise UI language a native speaker would write, in the brief's tone and the
@@ -64,7 +65,14 @@ come out generic.
      one).
    - Arrays: same number of items, same order.
    - Reuse `memory` unless the context differs. Follow the glossary.
-   - Keep it about as long as the source; buttons and tabs have little room.
+   - Keep it about as long as the source. Items with a `role` of button, tab, chip or menu item
+     have little room: prefer the shortest natural wording.
+   - When the source could mean two things ("Open" as a button or a status, "Balance" as money
+     or equilibrium) and the context doesn't settle it, add a short `note` saying how you read
+     it. Reviewers see it. Skip notes when the meaning is clear.
+   - Same source text, different meaning ("Delete account" for a sign-in account and for a
+     budget): translate each for its meaning and add a `note` saying how they differ, so the
+     consistency check doesn't flag it.
    - Android values: write plain text; apostrophes, quotes and `&` are escaped for you.
 
 3. Submit, using a file for anything non-trivial:
@@ -77,7 +85,8 @@ come out generic.
      {"target": "android", "locale": "hi", "key": "days_left", "value": {"one": "%d दिन बाकी", "other": "%d दिन बाकी"}}
    ]}
    ```
-   Copy `target`, `locale` and `key` from the batch items. Delete the file afterwards.
+   Copy `target`, `locale` and `key` from the batch items. Add `"note"` to an entry only for an
+   ambiguous source, or one worded differently on purpose. Delete the file afterwards.
 
 4. Read the result. Rejected entries list their errors: fix exactly those and resubmit only
    them. Accepted entries may have warnings (glossary, untranslated, whitespace): fix the
@@ -88,15 +97,19 @@ come out generic.
 ## 3. Finish
 
 - Run `localship validate`. It must have no errors.
+- Resolve or explicitly report coverage warnings. `validate --strict` checks completeness;
+  after review and approval, `validate --require-approved` also enforces approval. Unsupported
+  content blocks both checks; use the platform tools for that content and report the limitation.
 - Run `localship status` and report per locale: how many drafts were written, anything that
-  failed, warnings you left and why, and terms you were unsure of.
+  failed, warnings you left and why, and terms you were unsure of. Say which voice you followed
+  (especially a `defaultVoice`) so the user can change it.
 - **Don't approve your own drafts.** Suggest the user reviews them (the `localship-review` skill),
   then `localship approve`.
 - For a right-to-left language (Arabic, Hebrew, Persian, Urdu), or any first translation, tell the
   user what still needs a device: the layout mirrored, long text cut off, plurals at 0, 1, 2, 5
   and 11, switching language while the app is open, charts, amounts with a sign, and names
-  stored in data. Offer to look for these in the code (the `localship-extract` skill lists
-  them); Localship's checks only cover the translation files.
+  stored in data. Localship's checks only cover the translation files; the `localship-extract`
+  skill lists where to look in the code if the user wants that checked.
 - Never pass `--force` unless the user explicitly asks: it replaces translations a person
   wrote, reviewed or approved.