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 |
| ✨ Get Started |
shiplocal.onboarding.welcome |
Opens the guided onboarding flow that checks auth, project selection, and i18n readiness, then routes you to the next best action. |
| ⚙️ Shiplocal Settings |
shiplocal.settings.open |
Launches the settings webview showing auth status, linked project, detected translation paths, and quick actions. |
| 🔧 Setup i18n |
shiplocal.setup.i18n |
Runs automatic detection of your localisation framework, scaffolds missing files, and stores the translation paths with Shiplocal. |
| 📊 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. Each command respects the onboarding guard rails (ensureAllSetup) so you always know what to fix before moving forward.
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.
- Run
Shiplocal: ✨ Get Started to trigger the onboarding checklist. The flow will prompt you to:
- Sign in with your Shiplocal account (browser OAuth).
- Select or create a project destination.
- Detect your existing i18n setup or scaffold a natural-language-ready configuration.
- 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.
The extension’s scaffolding flows configure your framework (e.g. next-intl, react-i18next) to disable key separators so natural keys work seamlessly.
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.
- Translation path warnings - If Full Codebase Localisation reports missing translation directories, re-run
Shiplocal: 🔧 Setup i18n to detect or scaffold paths and push them to the backend.
- 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.
| |
