Shiplocal Assistant for VS Code
Accelerate 0-to-1 localisation by wrapping strings with natural language keys, guided automation, and AI-powered analysis directly inside VS Code.
Why Shiplocal?
- Natural language keys first - Ship internationalisation without inventing brittle identifier hierarchies; keys look exactly like the strings you write today.
- Workflow guardrails - Phase-based commands walk teams from discovery to full rollout, reducing the guesswork around pricing, setup, and review.
- Production-ready automation - Rule-based scanning, AI classification, and smart diff application create ready-to-commit changes and translation files.
- Built for multi-framework repositories - Supports React/Next.js today with expansion paths for Rails, Laravel, Vue, and more.
Primary Commands & Flows
| Command |
Palette ID |
When to use |
| ⚙️ Shiplocal Settings |
shiplocal.settings.open |
Central hub for configuration: authenticate, select project, configure framework and i18n paths. Opens automatically on first use. |
| 📊 Estimate Translation Project |
shiplocal.discovery.estimateProject |
Performs a rule-only scan to count strings and recommends the right pricing tier before you commit to a full AI run. |
| 🔐 Sign In |
shiplocal.auth.signIn |
Authenticates against the Shiplocal web app (browser-based) so the extension can access paid analysis features. |
| 📁 Select Project |
shiplocal.project.select |
Choose the Shiplocal project that will receive results and billing events for the current workspace. |
| 🚀 Full Codebase Localisation |
shiplocal.analysis.fullLocalisation |
End-to-end production run that batches files, classifies strings with LLMs, applies generated diffs, and writes translation files. |
| 🧪 Test 10 File Transformation |
shiplocal.analysis.testTenFiles |
Processes up to 10 files using the production pipeline so you can validate results before running a full localisation. |
The command palette shows these under the Shiplocal category. Commands validate that required project configuration is present before proceeding.
Getting Started
- Install the extension locally (
pnpm run vsce:package then install the .vsix) or from the Marketplace once published.
- Open your codebase in VS Code - preferably the repository root you plan to localise.
- Configure your project - The settings view opens automatically on first use. If not, run
Shiplocal: ⚙️ Shiplocal Settings:
- Sign in with your Shiplocal account (browser OAuth).
- Select or create a project destination.
- Configure your i18n setup:
- Set your framework (React, Next.js, Vue, Rails, Laravel, etc.)
- Specify your i18n library (e.g.,
next-intl, react-i18next, vue-i18n)
- Set the translation file path (e.g.,
messages/en.json)
- Set the translation directory (e.g.,
messages)
- For monorepos, set the root directory (e.g.,
apps/web)
- Use
Shiplocal: 📊 Estimate Translation Project to preview scope and pricing based on rule analysis.
- When ready, choose between
Shiplocal: 🧪 Test 10 File Transformation for a limited trial or Shiplocal: 🚀 Full Codebase Localisation for a production batch run.
Natural Language Keys, Explained
Shiplocal optimises for the first localisation rollout:
- Five-second adoption - Replace
"Welcome to our platform" with t("Welcome to our platform"). No namespace debates, no JSON edits mid-refactor.
- AI-native context - Large language models translate keyed strings accurately when the key is the sentence itself.
- Progressive enhancement - Start with the literal string; add context markers (
[button], [short]) only when variants emerge.
- Self-documenting diffs - Pull requests show human-readable strings even when translations are missing.
Configure your framework's i18n library (e.g. next-intl, react-i18next) to use natural language keys by disabling key separators in your i18n configuration.
Troubleshooting
- "No workspace folder" - Commands such as Estimate or Full Codebase Localisation require an open folder; open the repository root first.
- Authentication loops - Clear VS Code secrets for
shiplocal.session_token and re-run Shiplocal: 🔐 Sign In if tokens become invalid.
- Missing configuration - If commands report missing project configuration, open
Shiplocal: ⚙️ Shiplocal Settings and ensure all required fields are set (framework, i18n library, translation file path, translation directory).
- Translation path warnings - If Full Codebase Localisation reports missing translation directories, update the translation file path and directory in
Shiplocal: ⚙️ Shiplocal Settings.
- Monorepo setup - If you're working in a monorepo, set the
Root Directory field in settings to point to your project's subdirectory (e.g., apps/web).
- Diff conflicts - Review generated patches in the Problems panel; rerun the command after resolving merge conflicts.
Support
- Feedback & bugs - Share issues via your Shiplocal success channel or email the product team.
- Documentation - Learn more about phases, pricing, and the philosophy behind natural language keys in
PROJECT_OVERVIEW.md and on the Shiplocal docs site.
Last updated: September 2025.
| |
