🚀 i18n-ship

Ship your translations. Not your time.

Manage i18n translation JSON files directly in your codebase and sync them with AWS S3 in one command. AI-powered auto-translation. Agent rules for GitHub Copilot & Cursor.

🤔 Why i18n-ship?

Managing translations usually looks like this:

Open a web app → Add keys manually → Download JSON → Copy to your project → Upload to S3 → Repeat for every language...

i18n-ship eliminates all of that. You manage translations directly in your codebase and sync with AWS S3 in one command.

With AI agent rules, your AI assistant (Copilot/Cursor) automatically:

• 🔍 Finds hardcoded strings in your code
• 🔑 Generates proper i18n keys
• 🌍 Translates to all your languages
• 📝 Updates locale files

Zero manual work.

📦 Installation

npm install -D i18n-ship

Requirements: Node.js 18+

⚡ Quick Start

Get up and running in 60 seconds:

# 1. Interactive setup — creates config, env template, and locale files
npx i18n-ship init

# 2. Install AI agent rules for Copilot/Cursor (optional but recommended)
npx i18n-ship install-rules

# 3. Add your AWS credentials to .env
#    AWS_ACCESS_KEY_ID=your-key
#    AWS_SECRET_ACCESS_KEY=your-secret

# 4. You're ready! Push your translations
npx i18n-ship push stage

🛠️ Setup Guide

Step 1: Initialize your project

npx i18n-ship init

The setup wizard will:

| What it does | Details | |---|---| | 📁 Ask for your locales directory | Default: ./src/locales | | 🌍 Detect or ask for languages | e.g., en, tr, de, fr | | 🏠 Set your base language | Default: first language | | ☁️ Configure AWS S3 | Bucket, prefix, region | | 🤖 Enable AI translation (optional) | OpenAI-powered batch translation | | 📝 Create .i18nrc.json | Project configuration file | | 🔐 Add env template to .env | AWS credential placeholders | | 📦 Add npm scripts to package.json | Ready-to-use commands |

Step 2: Add AWS Credentials

Add your AWS credentials to .env:

AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

💡 Tip: Never commit .env to git. Make sure it's in your .gitignore.

Step 3: Install Agent Rules (Recommended)

npx i18n-ship install-rules

Choose your AI tool:

• GitHub Copilot → Copies rules to .github/prompts/translation.prompt.md
• Cursor → Copies rules to .cursor/rules/translation.mdc
• Both → Installs for both tools

📖 Commands

push — Upload translations to S3

npx i18n-ship push stage          # Push to staging
npx i18n-ship push production     # Push to production
npx i18n-ship push stage --yes    # Skip confirmation prompt

What happens:

1. Validates all locale JSON files
2. Shows file summary (keys per language)
3. Asks for confirmation
4. Uploads to s3://your-bucket/your-prefix/<env>/

pull — Download translations from S3

npx i18n-ship pull stage          # Pull from staging
npx i18n-ship pull production     # Pull from production
npx i18n-ship pull stage --yes    # Skip confirmation prompt

What happens:

1. Downloads all locale files from S3
2. Validates JSON integrity
3. Overwrites local files with remote versions

diff — Show missing translations

npx i18n-ship diff                # Show missing keys
npx i18n-ship diff --fix          # Auto-translate & add missing keys

Example output:

📊 Total unique keys: 145
   en.json: 145 keys
   tr.json: 140 keys
   de.json: 138 keys

❌ tr.json — 5 missing:
   dashboard.welcome
     └─ en: "Welcome back, {name}!"
   settings.theme.dark
     └─ en: "Dark mode"

translate — AI-powered translation

npx i18n-ship translate              # Translate all missing keys
npx i18n-ship translate --dry-run    # Preview without writing files
npx i18n-ship translate --source tr  # Use Turkish as source language

Requires: openai package + OPENAI_API_KEY in .env

Enable in .i18nrc.json:

{
  "ai": {
    "enabled": true,
    "provider": "openai",
    "model": "gpt-4.1"
  }
}

install-rules — Install AI agent rules

npx i18n-ship install-rules

Installs translation workflow rules for your AI assistant. After installation:

• Copilot: Type /translation in Copilot Chat
• Cursor: Rules auto-apply when working with translation files

help — Show all commands

npx i18n-ship help

⚙️ Configuration

The init command creates a .i18nrc.json file in your project root:

{
  "localesDir": "./src/locales",
  "languages": ["en", "tr", "de"],
  "baseLanguage": "en",
  "environments": ["stage", "production"],
  "s3": {
    "bucket": "my-translations-bucket",
    "prefix": "my-project",
    "region": "eu-west-1"
  },
  "ai": {
    "enabled": false,
    "provider": "openai",
    "model": "gpt-4.1"
  }
}

| Field | Description | Default | |---|---|---| | localesDir | Path to your locale JSON files | ./src/locales | | languages | Array of language codes | ["en", "tr"] | | baseLanguage | Source language for translations | "en" | | environments | Deployment environments | ["stage", "production"] | | s3.bucket | AWS S3 bucket name | — | | s3.prefix | S3 path prefix | — | | s3.region | AWS region | "eu-west-1" | | ai.enabled | Enable OpenAI translation | false | | ai.provider | AI provider | "openai" | | ai.model | AI model to use | "gpt-4.1" |

📂 Environment Variables

| Variable | Required | Description | |---|---|---| | AWS_ACCESS_KEY_ID | ✅ | AWS access key for S3 | | AWS_SECRET_ACCESS_KEY | ✅ | AWS secret key for S3 | | OPENAI_API_KEY | ❌ | Only if ai.enabled: true |

🧩 NPM Scripts

After init, these scripts are added to your package.json:

{
  "scripts": {
    "i18n:push:stage": "i18n-ship push stage",
    "i18n:push:prod": "i18n-ship push production",
    "i18n:pull:stage": "i18n-ship pull stage",
    "i18n:pull:prod": "i18n-ship pull production",
    "i18n:diff": "i18n-ship diff",
    "i18n:translate": "i18n-ship translate"
  }
}

🤖 AI Agent Integration

i18n-ship includes pre-built rules for AI coding assistants. When installed, your AI agent knows how to:

1. Extract hardcoded strings from your code
2. Generate consistent i18n keys (e.g., page.section.element)
3. Update all locale files with the new keys
4. Translate values to all configured languages
5. Follow your project's naming conventions

GitHub Copilot

npx i18n-ship install-rules  # Choose "GitHub Copilot"

Then in VS Code, use /translation in Copilot Chat to trigger the workflow.

Cursor

npx i18n-ship install-rules  # Choose "Cursor"

Cursor automatically applies rules when it detects translation-related work.

📋 Typical Workflow

1. Write code with hardcoded strings
2. Ask your AI agent to extract & translate  (or do it manually)
3. Run `npx i18n-ship diff` to verify
4. Run `npx i18n-ship push stage` to deploy to staging
5. Test your app
6. Run `npx i18n-ship push production` to go live

🗂️ Project Structure Example

my-project/
├── src/
│   └── locales/
│       ├── en.json          ← Base language
│       ├── tr.json          ← Turkish translations
│       └── de.json          ← German translations
├── .i18nrc.json             ← i18n-ship config
├── .env                     ← AWS credentials (gitignored)
├── .github/
│   └── prompts/
│       └── translation.prompt.md  ← Copilot rules
└── package.json

❓ FAQ

No. The OpenAI integration is fully optional. You can:

• Use diff --fix for free Google Translate-based translation
• Let your AI agent (Copilot/Cursor) handle translations
• Translate manually

The translate command (OpenAI) is for teams who want high-quality batch translations.

Your AWS credentials need these S3 permissions on your bucket:

• s3:PutObject (for push)
• s3:GetObject (for pull)
• s3:PutObjectAcl (if using public-read ACL)

Currently, i18n-ship is designed for AWS S3. Support for other storage providers (GCS, Azure Blob) is planned for future releases.

Currently, i18n-ship works with flat JSON key-value structures. Nested key support is planned.

📝 License

MIT © Muhammed Erdinc