### Initialize Lingo.dev Project

Source: https://lingo.dev/docs/cli/quick-start

Navigate to your project directory and run the 'lingo init' command to start the interactive setup process. This command guides you through account connection, project selection, locale configuration, and file structure setup.

```bash
cd my-project
lingo init
```

--------------------------------

### Source File Example

Source: https://lingo.dev/en/docs/cli/key-locking

This is an example of a source localization file.

```json
{
  "welcome": "Welcome to our platform",
  "brand": {
    "name": "Lingo.dev"
  },
  "config": {
    "apiUrl": "https://api.example.com"
  }
}
```

--------------------------------

### Install Lingo.dev CLI with npm

Source: https://lingo.dev/docs/cli/quick-start

Install the Lingo.dev CLI globally using npm. Ensure you have Node.js 18.0 or higher installed.

```bash
npm install -g lingo.dev
```

--------------------------------

### Install Lingo.dev CLI with bun

Source: https://lingo.dev/docs/cli/quick-start

Install the Lingo.dev CLI globally using bun. Ensure you have Node.js 18.0 or higher installed.

```bash
bun add -g lingo.dev
```

--------------------------------

### CI Example: GitHub Actions for Translation Generation

Source: https://lingo.dev/docs/react/compiler/build-modes

This example demonstrates how to set up a GitHub Actions workflow to automatically generate translations. It includes steps for checking out code, setting up Node.js, installing dependencies, building translations, and committing the updated metadata file.

```yaml
# .github/workflows/translate.yml
name: Generate Translations
on:
  push:
    branches: [main]

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      - run: npm run build
        env:
          LINGO_BUILD_MODE: translate
          LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}

      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "chore: update translations"
          file_pattern: ".lingo/metadata.json"
```

--------------------------------

### Install Lingo.dev CLI

Source: https://lingo.dev/llms-full.txt

Install the Lingo.dev CLI globally using npm, pnpm, yarn, or bun.

```bash
npm install -g lingo.dev
```

```bash
pnpm add -g lingo.dev
```

```bash
yarn global add lingo.dev
```

```bash
bun add -g lingo.dev
```

--------------------------------

### Install Lingo.dev Compiler

Source: https://lingo.dev/llms-full.txt

Install the Lingo.dev compiler as a development dependency using npm or pnpm.

```bash
npm install -D @lingo.dev/compiler
```

```bash
pnpm install @lingo.dev/compiler
```

--------------------------------

### Install Lingo.dev CLI with pnpm

Source: https://lingo.dev/docs/cli/quick-start

Install the Lingo.dev CLI globally using pnpm. Ensure you have Node.js 18.0 or higher installed.

```bash
pnpm add -g lingo.dev
```

--------------------------------

### Install Lingo.dev Compiler

Source: https://lingo.dev/en/docs/react/compiler/quick-start

Install the Lingo.dev Compiler as a development dependency using npm.

```bash
npm install -D @lingo.dev/compiler
```

--------------------------------

### Example Prompt for i18n-setup Agent

Source: https://lingo.dev/docs/react/mcp/github-copilot

This is an example prompt to initiate the i18n-setup agent in GitHub Copilot. It specifies the desired locales and the default locale for the project.

```text
Set up i18n for the following locales:

- en
- es

Use "en" as the default locale.

```

--------------------------------

### Minimal GitHub Actions Setup for Lingo.dev

Source: https://lingo.dev/en/docs/workflows/github

This is the most basic setup for the Lingo.dev GitHub Action. It commits translations directly to the main branch on every push. Ensure you have completed the CI/CD setup and have your LINGODOTDEV_API_KEY as a repository secret.

```yaml
name: Translate
on:
 push:
  branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Lingo.dev
      uses: lingodotdev/lingo.dev@main
      with:
        api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
```

--------------------------------

### Install Lingo.dev CLI with yarn

Source: https://lingo.dev/docs/cli/quick-start

Install the Lingo.dev CLI globally using yarn. Ensure you have Node.js 18.0 or higher installed.

```bash
yarn global add lingo.dev
```

--------------------------------

### Source File Example

Source: https://lingo.dev/docs/cli/key-preserving

This is an example of a source JSON file containing keys that might be marked for preservation.

```json
{
  "welcome": "Welcome to our platform",
  "legal": {
    "privacy": "We respect your privacy and protect your data.",
    "terms": "By using this service, you agree to our terms."
  }
}
```

--------------------------------

### Example .gitignore for Lingo.dev Compiler

Source: https://lingo.dev/docs/react/compiler/project-structure

Do not ignore the .lingo/ directory as it contains essential translation cache data. This example shows a typical .gitignore configuration.

```gitignore
# Do NOT ignore .lingo/ - it contains translation cache
node_modules/
dist/
.env
```

--------------------------------

### Install New Package

Source: https://lingo.dev/docs/react/compiler/migration-guide

Remove the old package and install the new one using npm.

```bash
npm uninstall lingo.dev
npm install @lingo.dev/compiler
```

--------------------------------

### Verify Lingo.dev CLI Installation

Source: https://lingo.dev/docs/cli/quick-start

Check if the Lingo.dev CLI is installed correctly by running the version command.

```bash
lingo --version
```

--------------------------------

### Install Lingo.dev Compiler

Source: https://lingo.dev/docs/react/compiler/nextjs

Install the Lingo.dev Compiler package using pnpm. This is a prerequisite for integrating the compiler with your Next.js application.

```bash
pnpm install @lingo.dev/compiler
```

--------------------------------

### Full Lingo.dev CLI Configuration Example

Source: https://lingo.dev/docs/cli/configuration

A comprehensive example of an `i18n.json` file, demonstrating locale settings, bucket configurations with key path rules, and engine connection.

```json
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["brand/name", "brand/tagline"],
      "ignoredKeys": ["internal/*"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  },
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}
```

--------------------------------

### Opt-in Translation Example (Included)

Source: https://lingo.dev/en/docs/react/compiler/project-structure

In opt-in mode, files starting with the `'use i18n'` directive are translated. This example shows a component where the text will be translated.

```tsx
'use i18n';

export function Welcome() {
  return <h1>Welcome to our app</h1>;
  // This text IS translated
}
```

--------------------------------

### Progress Event Message Example

Source: https://lingo.dev/docs/api/provisioning

The server broadcasts this message as each workflow step starts or completes.

```json
{
 "type": "provisioning.progress",
 "jobId": "pjb_A1b2C3d4E5f6G7h8",
 "step": "crawling",
 "detail": "Crawling source URLs..."
}
```

--------------------------------

### Opt-in Translation Example

Source: https://lingo.dev/docs/react/compiler/project-structure

In opt-in mode, files starting with the 'use i18n' directive are translated. Files without the directive are skipped.

```tsx
'use i18n';

export function Welcome() {
  return <h1>Welcome to our app</h1>;
  // This text IS translated
}
```

```tsx
export function InternalAdmin() {
  return <h1>Admin Dashboard</h1>;
  // This text is NOT translated
}
```

--------------------------------

### Initialize Lingo.dev project

Source: https://lingo.dev/en/docs/cli/setup

Run the init command to set up Lingo.dev in your project. For Windows users, if 'npx lingo.dev' fails, install the package globally first.

```bash
npx lingo.dev@latest init
```

```bash
npm install lingo.dev@latest
npx lingo
```

--------------------------------

### Initialize Lingo.dev Project

Source: https://lingo.dev/docs/cli/setup

Run the init command to set up Lingo.dev in your project. For Windows users, if 'npx lingo.dev' fails, install the package globally first using 'npm install lingo.dev@latest' and then use 'npx lingo'.

```bash
npx lingo.dev@latest init
```

--------------------------------

### List Localization Jobs

Source: https://lingo.dev/docs/api/localization

Example of a GET request to list localization jobs, with optional filters for engine ID and status, and pagination parameters.

```http
GET /jobs/localization?engineId=eng_abc123&status=completed&limit=20&cursor=...
```

--------------------------------

### Progress Event Example

Source: https://lingo.dev/docs/api/provisioning

This message is broadcast as each workflow step in the provisioning job starts or completes. It includes the job ID, the current step, and a detail message about the progress.

```json
{
  "type": "provisioning.progress",
  "jobId": "pjb_A1b2C3d4E5f6G7h8",
  "step": "crawling",
  "detail": "Crawling source URLs..."
}
```

--------------------------------

### Specify Target Locales in Configuration

Source: https://lingo.dev/en/docs/cli/supported-locales

Configure the source and target locales for localization in your project's configuration file. This example shows a common setup for multiple target languages.

```json
{
 "locale": {
  "source": "en",
  "targets": ["es", "fr", "de", "ja"]
 }
}
```

--------------------------------

### Feature Branch Workflow with Full Configuration

Source: https://lingo.dev/docs/workflows/bitbucket

This example demonstrates a feature branch workflow with custom configurations for API keys, pull request titles, commit messages, and working directories. It's suitable for monorepos and advanced setups.

```yaml
image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Translate
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                LINGODOTDEV_API_KEY: "${MY_LINGODOTDEV_API_KEY}"
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"

```

--------------------------------

### Lingo.dev CLI Configuration with Multiple Files

Source: https://lingo.dev/en/guides/android-app-localization

Example of an i18n.json configuration that includes multiple XML resource files for Android localization.

```json
{
 "buckets": {
 "android": {
 "include": [
 "app/src/main/res/values-[locale]/strings.xml",
 "app/src/main/res/values-[locale]/arrays.xml"
 ]
 }
 }
}
```

--------------------------------

### Minimal GitHub Actions Setup for Translation

Source: https://lingo.dev/docs/integrations/github

This basic setup commits translations directly to the main branch on every push. Ensure you have completed the CI/CD setup and stored your LINGODOTDEV_API_KEY as a repository secret.

```yaml
name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lingo.dev
        uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
```

--------------------------------

### Get Help with Lingo.dev CLI

Source: https://lingo.dev/docs/cli/quick-start

Access help documentation for the Lingo.dev CLI. Use '--help' for general commands or specific commands for detailed usage.

```bash
# Show help for all commands
lingo --help

# Show help for a specific command
lingo run --help
```

--------------------------------

### Example of Source and Translated Files with Key Locking

Source: https://lingo.dev/docs/cli/key-locking

Demonstrates how locked keys retain their source values in target files, while untranslated keys are processed normally. Only `welcome` is translated in this example.

```json
{
  "welcome": "Welcome to our platform",
  "brand": {
    "name": "Lingo.dev"
  },
  "config": {
    "apiUrl": "https://api.example.com"
  }
}
```

```json
{
  "welcome": "Bienvenido a nuestra plataforma",
  "brand": {
    "name": "Lingo.dev"
  },
  "config": {
    "apiUrl": "https://api.example.com"
  }
}
```

--------------------------------

### Define i18n-setup Agent for GitHub Copilot

Source: https://lingo.dev/en/docs/react/mcp/github-copilot

Create this markdown file in `.github/agents/i18n-setup.md` to define an agent that specializes in setting up internationalization. It uses a checklist-driven approach via the `lingo/*` tools.

```markdown
---
name: i18n-setup
description: Expert at implementing internationalization (i18n) in web applications using a systematic, checklist-driven approach.
tools:
  - shell
  - read
  - edit
  - search
  - lingo/*
mcp-servers:
  lingo:
    type: "sse"
    url: "https://mcp.lingo.dev/main"
    tools: ["*"]
---

You are an i18n implementation specialist. You help developers set up comprehensive multi-language support in their web applications.

## Your Workflow

**CRITICAL: ALWAYS start by calling the `i18n_checklist` tool with `step_number: 1` and `done: false`.

This tool will tell you exactly what to do. Follow its instructions precisely:

1. Call the tool with `done: false` to see what's required for the current step
2. Complete the requirements
3. Call the tool with `done: true` and provide evidence
4. The tool will give you the next step - repeat until all steps are complete

**NEVER skip steps. NEVER implement before checking the tool. ALWAYS follow the checklist.**
```

--------------------------------

### Webhook Payload Examples

Source: https://lingo.dev/en/docs/api/localization

Examples of JSON payloads received for translation completion and failure events.

```APIDOC
## Webhook Payload Examples

### Translation Completed Payload

```json
{
  "type": "translation.completed",
  "jobId": "ljb_A1b2C3d4E5f6G7h8",
  "groupId": "ljg_A1b2C3d4E5f6G7h8",
  "sourceLocale": "en",
  "targetLocale": "de",
  "data": {
    "id": "course_101",
    "title": "Einführung in maschinelles Lernen",
    "steps": [
      { "heading": "Was ist ML?", "body": "Maschinelles Lernen ist ein Teilbereich der künstlichen Intelligenz." },
      { "heading": "Überwachtes Lernen", "body": "Trainieren eines Modells mit gelabelten Daten." }
    ],
    "metadata": { "author": "Dr. Smith", "difficulty": "beginner" }
  }
}
```

### Translation Failed Payload

```json
{
  "type": "translation.failed",
  "jobId": "ljb_C3d4E5f6G7h8I9j0",
  "groupId": "ljg_A1b2C3d4E5f6G7h8",
  "sourceLocale": "en",
  "targetLocale": "ja",
  "error": "Model timeout after 30 seconds"
}
```
```

--------------------------------

### Webhook Payload Examples

Source: https://lingo.dev/docs/api/localization

Examples of JSON payloads received for completed and failed translation jobs.

```APIDOC
## Webhook Payload Examples

### Translation Completed Payload

This is the payload structure when a translation job is successfully completed.

```json
{
  "type": "translation.completed",
  "jobId": "ljb_A1b2C3d4E5f6G7h8",
  "groupId": "ljg_A1b2C3d4E5f6G7h8",
  "sourceLocale": "en",
  "targetLocale": "de",
  "data": {
    "id": "course_101",
    "title": "Einführung in maschinelles Lernen",
    "steps": [
      { "heading": "Was ist ML?", "body": "Maschinelles Lernen ist ein Teilbereich der künstlichen Intelligenz." },
      { "heading": "Überwachtes Lernen", "body": "Trainieren eines Modells mit gelabelten Daten." }
    ],
    "metadata": { "author": "Dr. Smith", "difficulty": "beginner" }
  }
}
```

### Translation Failed Payload

This is the payload structure when a translation job fails.

```json
{
  "type": "translation.failed",
  "jobId": "ljb_C3d4E5f6G7h8I9j0",
  "groupId": "ljg_A1b2C3d4E5f6G7h8",
  "sourceLocale": "en",
  "targetLocale": "ja",
  "error": "Model timeout after 30 seconds"
}
```
```

--------------------------------

### Prompt for Localization Engine Setup

Source: https://lingo.dev/en/guides/mcp-engine-setup

Use this prompt with your AI coding assistant to create and configure a new localization engine. Replace the placeholder URL with your product's content URL.

```text
Create a localization engine called 'My Product' for localizing into
German, French, Japanese, and Spanish. Study the content at the URL
below to understand our tone, terminology, and audience. Then configure
everything in one pass: brand voices for each locale (and English),
glossary entries for terms that need consistent translations or should
stay untranslated, and locale-specific linguistic instructions.

https://docs.yourproduct.com

```