localship 0.1.0 → 0.3.0

package/README.md

@@ -6,6 +6,7 @@
 
 Free and open source · No account, no server · Any AI model · Every translation checked
 
+[![npm](https://img.shields.io/npm/v/localship?color=cb3837&logo=npm)](https://www.npmjs.com/package/localship)
 [![CI](https://github.com/jigarfumakiya/localship/actions/workflows/ci.yml/badge.svg)](https://github.com/jigarfumakiya/localship/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)](https://modelcontextprotocol.io)
@@ -31,39 +32,41 @@ no server, no monthly bill.
 
 - 🆓 **Free and open source.** MIT-licensed. You pay only for your own AI usage, or nothing with a
   local model.
-- 🤖 **Works with the AI you already use.** Your coding agent's own model, or Claude, GPT, Gemini,
-  OpenRouter, or a local model through Ollama.
-- 🛡️ **Catches broken translations.** Placeholders, plural forms, Android escaping and markup are
-  checked in code before anything is written. Failures go back to the AI with the reason.
+- 🤖 **Your AI, your model.** Your coding agent's own model, or Claude, GPT, Gemini, OpenRouter
+  or Ollama.
+- 🛡️ **Catches broken translations.** Placeholders, plural forms, escaping and markup are checked
+  in code before anything is written. Failures go back to the AI with the reason.
 - 🧠 **More context for the AI.** Each string comes with the code that uses it, its comment, your
   glossary and voice notes, and earlier translations of the same text.
-- 🔒 **Stays in your repo.** No server, no account, no upload. Your files, written the way Android
-  Studio and Xcode write them.
+- 🔒 **Your files, your workflow.** No Localship server or account. Translation files stay in your
+  repo, formatted the way your tools write them. You choose the AI that receives their content.
+- ✅ **Check before release.** Require current, approved translations in CI with
+  `localship validate --require-approved`. No model call or API key needed for the check.
 - 💻 **Runs anywhere.** Claude Code, Cursor, VS Code, Codex, Gemini CLI, Claude Desktop or the
   terminal, on macOS, Linux and Windows.
 
 ### 🤔 Why use Localship?
 
-Your AI can already translate a strings file if you ask. Here's what changes with Localship:
-
 | | ❌ Asking an AI directly | ✅ With Localship |
 |---|---|---|
-| Placeholders like `%1$s` | Sometimes dropped, and the app crashes on that screen | Checked before writing; sent back to fix |
-| Plural forms | Arabic often gets 2 forms instead of 6 | The right forms for every language, from Unicode CLDR |
-| Android escaping | An unescaped apostrophe breaks the build | Escaped for you |
-| Consistent terms | "Budget" translated three ways | Glossary, voice notes and earlier translations |
-| Changing copy | Everything is translated again | Only changed strings are redone, with the old and new text |
-| Your translator's fixes | Overwritten | Kept unless you ask |
+| Context | One string at a time | Code, comments, brief and glossary |
+| Placeholders | Sometimes dropped | Checked before writing |
+| Plural forms | Often incomplete | Every form each language needs |
+| Escaping and markup | Can break the build | Checked and escaped |
+| Terms and tone | Drift across strings | Same glossary and voice everywhere |
+| Changed copy | Everything redone | Only what changed |
+| Your edits | Overwritten | Kept |
+
+For a comparison with Lingo.dev, Crowdin, Lokalise and i18n Ally, see the
+[plugin review](docs/plugin-review.md).
 
 ## 🎬 See it in action
 
 ```
 You:    Translate this app into Hindi and Arabic.
-Agent:  Found 18 strings (2 plurals, 3 with placeholders). I'll add a short brief and
-        glossary, and keep "Jotter Pro" as written. Say "start translating" to go.
-
-You:    Start translating.
-Agent:  36 translations written as drafts, 0 errors. Arabic has all six plural forms.
+Agent:  Translating 18 strings into Hindi and Arabic…
+        36 translations written as drafts, 0 errors. Arabic has all six plural forms.
+        Hindi addresses the user as आप, and "Jotter Pro" is kept as written.
 
 You:    Review the Arabic, then approve them.
 Agent:  Two small fixes made. All approved.
@@ -127,47 +130,52 @@ Wherever your app is today, one sentence gets it started.
 Android string arrays and plurals, String Catalog plural variations, and gettext plural forms are
 all supported.
 
-## 🚀 Install
-
-Needs [Node.js](https://nodejs.org) 22 or newer.
+Apple device/nested variations and substitutions, and Android strings in configuration-specific
+folders such as `values-ar-night`, are preserved but not translated or validated. Localship reports
+these coverage gaps; `validate --strict` and `--require-approved` fail rather than claim completeness.
+See [platform verification](skills/localship-extract/references/platform-localization.md) for native
+build, language setup and device checks.
 
-### ⭐ The easiest way
+## 🚀 Install
 
-**Claude Code:** install the plugin, which includes the server and the skills.
+**Claude Code plugin**
 
 ```
 /plugin marketplace add jigarfumakiya/localship
 /plugin install localship@localship
 ```
 
-**Codex, Cursor, Gemini CLI and other agents:** one command adds the Localship skills,
-step-by-step playbooks your agent follows. The first time, it offers to install the Localship
-command line it uses.
+**Claude Code, Codex, Gemini CLI and other CLIs:** add the server, then the skills.
 
 ```sh
-npx skills add jigarfumakiya/localship
+claude mcp add localship -- npx -y localship mcp   # Claude Code
+codex mcp add localship -- npx -y localship mcp    # Codex
+gemini mcp add localship npx -y localship mcp      # Gemini CLI
+npx skills add jigarfumakiya/localship             # the skills, for any agent
 ```
 
-Then open your app and ask: *"Translate this app into Hindi and Arabic."*
+**Cursor and VS Code**
+
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=localship&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImxvY2Fsc2hpcCIsIm1jcCJdfQ%3D%3D)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_server-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522localship%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522localship%2522%252C%2522mcp%2522%255D%257D)
+
+Add the skills too: `npx skills add jigarfumakiya/localship`.
+
+Now ask your agent: *"Translate this app into Hindi and Arabic."* Needs Node.js 22 or newer.
 
 ### 🔌 Other tools
 
-Add Localship as an MCP server.
+Add this MCP server to your tool's config:
 
 ```json
 { "mcpServers": { "localship": { "command": "npx", "args": ["-y", "localship", "mcp"] } } }
 ```
 
-| Tool | Where the config goes |
+| Tool | Config file |
 |---|---|
-| Claude Code (without the plugin) | `claude mcp add localship -- npx -y localship mcp` |
-| Cursor | `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` |
-| VS Code | `.vscode/mcp.json`, with `"servers"` instead of `"mcpServers"` and `"type": "stdio"` added |
-| Gemini CLI | `.gemini/settings.json` |
-| Codex | `~/.codex/config.toml`: `[mcp_servers.localship]` with `command = "npx"` and `args = ["-y", "localship", "mcp"]` |
-| Claude Desktop | `claude_desktop_config.json`, with `"-C", "/path/to/your/app"` added before `"mcp"` |
-
-The first start takes a minute while it installs.
+| Cursor | `.cursor/mcp.json` |
+| VS Code | `.vscode/mcp.json` (use `"servers"`) |
+| Claude Desktop | `claude_desktop_config.json` (add `"-C", "/path/to/app"` before `"mcp"`) |
 
 <details>
 <summary><b>MCP tools</b></summary>
@@ -176,8 +184,8 @@ Your agent picks these itself; you just ask. 👀 marks tools that only read and
 
 | Tool | What it does |
 |---|---|
-| `localship_plan` 👀 | Looks at the project and returns one plan for a request: what it found, blockers, steps and defaults |
-| `localship_start` | Sets up a confirmed plan: config, default voice notes and glossary, never overwriting yours |
+| `localship_plan` 👀 | Looks at what a request involves: files, strings to translate, anything in the way |
+| `localship_start` | Writes the config for the languages, or adds them to it |
 | `localship_status` 👀 | Progress per language: missing, changed, drafts, approved |
 | `localship_validate` 👀 | Checks placeholders, plural forms, escaping, markup and the glossary |
 | `localship_detect` 👀 | Finds translation files in the repo |
@@ -198,9 +206,10 @@ Your agent picks these itself; you just ask. 👀 marks tools that only read and
 
 - **Stays in your project.** Localship reads and writes only your translation files and the
   `.localship/` folder. Changes to your code are made by your agent, where you can see them.
-- **No Localship server.** No account, no telemetry. The only calls Localship makes go to a model
-  API you set up, with your own key. With your coding agent's model or a local Ollama, it sends
-  nothing over the internet.
+- **No Localship server.** No account, no telemetry. Localship's model calls go to the provider
+  you configure. When you use a cloud coding agent, that agent may send strings and context to
+  its model provider. Validation runs locally without model calls; translation can also stay
+  local when you use a locally hosted model.
 - **Nothing is final until you say so.** Translations are written as drafts, and hand edits and
   approved translations are never replaced unless you ask.
 
@@ -216,6 +225,7 @@ localship start hi,ar --model anthropic:claude-sonnet-5-5   # set up and transla
 localship status                                            # progress per language
 localship validate                                          # exits 1 on errors
 localship approve --locale hi                               # after review
+localship validate --require-approved                       # release / CI check
 ```
 
 Every command, option and config key is in the [reference](docs/reference.md).