agentDocTemplate top-level constant

String const agentDocTemplate

Implementation

const String agentDocTemplate = r'''
# Localizable CLI & Integration Guide for LLM Agents

This guide documents the `localizable` CLI tool, project concepts, and integration patterns for Flutter and Pure Dart applications.
When executing commands from automated agents or scripts, use the `--json` flag to receive structured JSON output.

---

## 1. Authentication & Configuration

The CLI supports two authentication modes:

### A. Project Read-Only Mode (`localizable_project.json`)
- **File:** `localizable_project.json` in the project root.
- **Scope:** Read-only access to export and download generated Dart/Flutter localization code.
- **Commands:** `localizable update`.
- **Schema:**
  ```json
  {
    "id": "<project-id>",
    "jws": "<project-export-jws-token>"
  }
  ```

### B. User Account Full-Access Mode (`localizable_user.json`)
- **File:** `localizable_user.json` in the project root, current directory, or user home (`~/.localizable/localizable_user.json`).
- **Alternative:** Pass `--user-key <jws>` or set environment variable `LOCALIZABLE_USER_KEY`.
- **Scope:** Full CRUD access to users, groups, projects, translations, localizations, variables, tags, machine translations, issues, and project imports.
- **Schema:**
  ```json
  {
    "jws": "<user-account-jws-token>"
  }
  ```

---

## 2. Core Concepts: Keys, Variables & Formats

### Naming Conventions & Rules
- **Translation Keys:**
  - Must always be in **`snake_case`**.
  - Must contain only lowercase letters (`a-z`) and underscores (`_`).
  - **Cannot contain numbers** (no digits `0-9`).
  - *Valid examples:* `welcome_user`, `sign_in_button`, `order_status_pending`.
  - *Invalid examples:* `welcomeUser` (camelCase), `welcome-user` (kebab-case), `item_1` (contains digits).
- **Variables:**
  - Must always be in **`camelCase`**.
  - Must contain only letters (`a-z`, `A-Z`).
  - **Cannot contain numbers** (no digits `0-9`).
  - *Valid examples:* `${userName}`, `${itemCount}`, `${startDate}`.
  - *Invalid examples:* `${user_name}` (snake_case), `${item1}` (contains digits), `${user-name}` (kebab-case).

### Variable Syntax in Translations
Translations support dynamic placeholders using the `${variableName}` syntax:
```
Hi ${userName}, welcome to Localizable! Today is ${currentDate} and you have ${unreadCount} in your inbox.
```

### Supported Variable Formats
| Format | CLI Option | Description |
| :--- | :--- | :--- |
| **Text** | `text` | Plain string parameters (e.g. `${userName}`, `${itemTitle}`). |
| **Number** | `number` | Formatted numeric values (e.g. `${itemCount}`, `${scoreValue}`). |
| **Measurement** | `measurement` | Unit and symbol measurements (e.g. `${distanceMeters}`, `${speedValue}`). |
| **Date** | `date` | Date/DateTime objects formatted according to the active locale. |
| **Gender** | `gender` | Gender-specific variations (`male`, `female`, `other`). |
| **Plural** | `plural` | Pluralization rules (`zero`, `one`, `two`, `few`, `many`, `other`). |
| **Static** | `static` | Applies custom styling/spans without dynamic substitution. |
| **Custom** | `custom` | Custom variable formatting with defined field names. |

### Plural & Gender Categories
- **Plural fields:** `zero`, `one`, `two`, `few`, `many`, `other`.
  Inside plural templates, use `${value}` for the quantity placeholder.
  *Example (One):* `${value} unread message`
  *Example (Other):* `${value} unread messages`
- **Gender fields:** `male`, `female`, `other`.

### Translation Keys vs. Localizations (Mandatory Rule)
- **Translation Key (`localizable translation upsert`):** Registers an identifier (e.g. `welcome_user`, `login_button`). Creating a key *only creates the key identifier record and does not assign any text*.
- **Localization (`localizable localization upsert`):** Assigns actual text strings to a translation key for a specific locale (e.g. `en` -> `"Welcome!"`).
- **Mandatory Agent Rule:** Whenever you create a translation key, **you MUST ALWAYS immediately create its main localization text** (preferred English `en`) using `localizable localization upsert` without the `--auto-translate` CLI parameter. Never create a translation key without filling in its main localization text!
- **Main Language First & Auto-Translate Behavior:**
  - **`--auto-translate` should preferably be excluded in CLI commands.**
  - **Always fill in first the main language localization text without the `--auto-translate` CLI parameter.**
  - **When the main language is upserted, the target languages are automatically updated** when auto-translate is set to enabled on the project level.
  - **Only set the localization text for a target language when auto-translate is not set to enabled on the project level** (or when providing a custom manual translation override).

---

## 3. Recommended Agent Workflows

### Workflow 1: Create a Project
1. **Create the Project Remotely:**
   *Note: English (`en`) is the preferred main locale (`--main-locale "en"`) when creating a project.*
   ```bash
   localizable project upsert \
     --name "My Awesome App" \
     --main-locale "en" \
     --target-locales "nl,es,de,fr" \
     --description "Mobile app localization" \
     --export-flutter \
     --export-dart \
     --json
   ```
   *Returns `{ "id": "<project-id>", "name": "My Awesome App", ... }`.*

2. **Save Project Configuration Locally (`localizable_project.json`):**
   ```bash
   localizable project config --save --json
   ```
   *Creates `localizable_project.json` in the project root with the Project ID and export token. Once saved, all subsequent commands (`translation`, `tag`, `issue`, `update`) automatically infer the Project ID.*

---

### Workflow 2: Add Translation Keys & Localizations

> [!IMPORTANT]
> Creating a translation key only creates the key identifier. LLM agents **MUST ALWAYS immediately populate the main localization text** (preferred English `en`) using `localizable localization upsert` without the `--auto-translate` CLI parameter. Never leave a translation key empty without its main localization text. When the main language is upserted, target languages are automatically updated if auto-translate is enabled at the project level. Only set localization text for a target language when auto-translate is not set to enabled on the project level.

1. **Create Translation Key:**
   ```bash
   # When localizable_project.json is present (or user has a single project):
   localizable translation upsert --key "welcome_user" --json

   # Or explicitly passing project-id:
   localizable translation upsert --project-id "<project-id>" --key "welcome_user" --json
   ```
   *Returns `{ "id": "<translation-id>", "key": "welcome_user", "projectId": "<project-id>", ... }`.*

2. **Add Main Localization Text (Mandatory — Preferred English `en`):**
   ```bash
   # English (main / source locale text — REQUIRED for every key; exclude --auto-translate)
   localizable localization upsert \
     --translation-id "<translation-id>" \
     --locale-id "en" \
     --text "Hi ${userName}, welcome! You have ${unreadCount} in your inbox." \
     --json
   ```
   *Note: `--auto-translate` should preferably be excluded in CLI commands. Always fill in the main language localization text first without `--auto-translate`. When the main language is upserted, target languages are automatically updated if auto-translate is set to enabled on the project level.*

3. **Add Target Localizations (Only when auto-translate is not enabled on project level, or for manual overrides):**
   ```bash
   # Dutch (target locale — only set if auto-translate is not enabled on project level, or to override)
   localizable localization upsert \
     --translation-id "<translation-id>" \
     --locale-id "nl" \
     --text "Hoi ${userName}, welkom! Je hebt ${unreadCount} in je inbox." \
     --json
   ```

---

### Workflow 3: Add Variables to Translations (Plurals, Formats)
1. **Create the Plural Variable:**
   ```bash
   localizable variable upsert \
     --translation-id "<translation-id>" \
     --name "unreadCount" \
     --format plural \
     --position 1 \
     --json
   ```
   *Returns `{ "id": "<variable-id>", ... }`.*

2. **Add Plural Localizations:**
   ```bash
   # English plural rules (main language first; exclude --auto-translate)
   localizable variable-localization upsert \
     --variable-id "<variable-id>" \
     --locale-id "en" \
     --field "one" \
     --text "${value} unread message" \
     --json

   localizable variable-localization upsert \
     --variable-id "<variable-id>" \
     --locale-id "en" \
     --field "other" \
     --text "${value} unread messages" \
     --json

   # Target locales (e.g. Dutch) are automatically updated when auto-translate is enabled on the project level.
   # Only set target localization text when auto-translate is not set to enabled on the project level (or to override):
   localizable variable-localization upsert \
     --variable-id "<variable-id>" \
     --locale-id "nl" \
     --field "one" \
     --text "${value} ongelezen bericht" \
     --json

   localizable variable-localization upsert \
     --variable-id "<variable-id>" \
     --locale-id "nl" \
     --field "other" \
     --text "${value} ongelezen berichten" \
     --json
   ```

---

### Workflow 4: Machine Translate Text
Translate text on-demand from source to target locale:
```bash
localizable translate \
  --source-locale "en" \
  --target-locale "es" \
  --text "Welcome to our application!" \
  --json
```
*Returns `{ "text": "¡Bienvenido a nuestra aplicación!" }`.*

---

### Workflow 5: Sync & Generate Dart/Flutter Code
Generate and unpack the latest type-safe code into `lib/` (or `lib/src/`):
```bash
localizable update
```
- Reads `localizable_project.json`.
- Detects project type (Flutter or plain Dart).
- Verifies/adds `intl` dependency in `pubspec.yaml`.
- Unpacks generated files (`localizable.dart`, `messages_*.dart`).

---

### Workflow 6: Check Translation Issues & Validation Warnings
```bash
localizable issue list-by-project --json
```

---

## 4. Code Integration Guide

### A. Flutter Applications

#### 1. Configure Dependencies (`pubspec.yaml`)
```yaml
dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: ^0.20.3
```

#### 2. Configure `MaterialApp`
```dart
import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:my_app/localizable.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Localizable App',
      localizationsDelegates: const [
        Localizable.delegate,
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],
      supportedLocales: Localizable.supportedLocales,
      home: const HomePage(),
    );
  }
}
```

#### 3. Access Generated Translations

The **preferred method** when using Localizable in Flutter widgets is defining `final localizable = Localizable.of(context);` at the beginning of the `build` method.

```dart
class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    // Preferred: Define localizable at the beginning of the build method
    final localizable = Localizable.of(context);

    return Scaffold(
      appBar: AppBar(
        title: Text(localizable.app_title),
      ),
      body: Column(
        children: [
          // Basic typed translation call:
          Text(
            localizable.welcome_user(
              userName: 'Alex',
              currentDate: DateTime.now(),
              unreadCount: 3,
            ),
          ),

          // RichText with styled TextSpan:
          RichText(
            text: localizable.welcome_userTextSpan(
              context: context,
              userName: 'Alex',
              currentDate: DateTime.now(),
              unreadCount: 3,
              fullTextStyle: Theme.of(context).textTheme.bodyLarge,
              userNameStyle: const TextStyle(fontWeight: FontWeight.bold, color: Colors.blue),
            ),
          ),
        ],
      ),
    );
  }
}
```

#### 4. iOS Configuration (`ios/Runner/Info.plist`)
```xml
<key>CFBundleLocalizations</key>
<array>
    <string>en</string>
    <string>nl</string>
    <string>es</string>
</array>
```

---

### B. Pure Dart Applications

```dart
import 'package:my_package/localizable.dart';

void main() async {
  await Localizable.load(const Locale('en'));

  final message = Localizable.current.welcome_user(
    userName: 'Server',
    currentDate: DateTime.now(),
    unreadCount: 1,
  );

  print(message);
}
```

---

## 5. Complete CLI Command Reference

### Global Options
- `--json` `[Optional]`: Output results in structured JSON format (recommended for agents).
- `-i, --input-path <dir>` `[Optional, default: .]`: Base directory path containing `localizable_project.json` / `pubspec.yaml`.
- `-o, --output-path <dir>` `[Optional, default: input-path]`: Output directory for generated code / exports.
- `--user-config <file>` `[Optional]`: Path to `localizable_user.json`.
- `--user-key <jws>` `[Optional]`: Direct user account JWS authentication key.
- `--project-config <file>` `[Optional]`: Path to `localizable_project.json`.
- `--project-key <jws>` `[Optional]`: Direct project JWS authentication key.
- `--project-id <id>` `[Optional]`: Target Project ID (automatically inferred from `localizable_project.json` when omitted).
- `-d, --debug` `[Optional]`: Use localhost backend for development/testing.
- `-v, --version` `[Optional]`: Display CLI version.
- `-h, --help` `[Optional]`: Display help and command usage.

---

### Commands Summary Table

| Command | Subcommands | Description |
| :--- | :--- | :--- |
| `init` | *(none)* | Creates `LOCALIZABLE.md` in project root |
| `update` | *(none)* | Syncs remote export to local Dart/Flutter codebase |
| `user` | `get` | Manage current user account |
| `group` | `primary`, `get`, `list`, `upsert`, `delete` | Manage workspace groups |
| `project` | `list`, `get`, `upsert`, `delete`, `config`, `import` | Manage projects |
| `locale` | `list`, `get` | List supported languages/locales |
| `translation` | `list`, `search`, `get`, `upsert`, `copy`, `delete` | Manage translation keys |
| `localization` | `list`, `get`, `find`, `upsert`, `upsert-batch`, `delete` | Manage localized texts for keys |
| `variable` | `list`, `get`, `upsert`, `delete` | Manage variables for keys |
| `variable-localization` | `list`, `get`, `find`, `upsert`, `upsert-batch`, `delete` | Manage localized values for variables |
| `tag` | `list-by-project`, `list-by-translation`, `get`, `upsert`, `delete`, `add-translation`, `remove-translation` | Manage tags and tag associations |
| `translate` | *(none)* | Machine-translate text |
| `issue` | `list-by-project`, `list-by-translation` | Inspect validation issues |

---

### Subcommand Details

#### `localizable init`
- `--path <path>` `[Optional, default: .]`: Directory where `LOCALIZABLE.md` will be created.
- `--filename <name>` `[Optional, default: LOCALIZABLE.md]`: Filename for the markdown documentation.
- `--force` `[Optional]`: Overwrite existing documentation file if present.

#### `localizable update`
- `-i, --input-path <dir>` `[Optional, default: .]`: Project root directory containing `localizable_project.json`.
- `-o, --output-path <dir>` `[Optional, default: input-path]`: Output directory for generated Dart/Flutter code.

#### `localizable user`
- `localizable user get`: Return current authenticated user profile (Requires user authentication).


#### `localizable group`
- `localizable group primary`: Get primary workspace group for user.
- `localizable group get --id <groupId>`:
  - `--id <groupId>` `[Required]`: Group ID.
- `localizable group list [--user-id <userId>]`:
  - `--user-id <userId>` `[Optional]`: Filter by user ID (defaults to current user).
- `localizable group upsert --name <name> [--id <groupId>] [--user-id <userId>] [--description <desc>]`:
  - `--name <name>` `[Required]`: Group name.
  - `--id <groupId>` `[Optional]`: Group ID (leave empty to create a new group).
  - `--user-id <userId>` `[Optional]`: Owner user ID (defaults to current user).
  - `--description <desc>` `[Optional]`: Group description.
- `localizable group delete --id <groupId>`:
  - `--id <groupId>` `[Required]`: Group ID to delete.

#### `localizable project`
- `localizable project list [--group-id <groupId>]`:
  - `--group-id <groupId>` `[Optional]`: Filter projects by group ID (lists all projects if omitted).
- `localizable project get [--id <projectId>]`:
  - `--id <projectId>` `[Optional]`: Project ID (defaults to ID from `localizable_project.json` or `--project-id`).
- `localizable project upsert --name <name> [options]`:
  - `--name <name>` `[Required]`: Project name.
  - `--id <projectId>` `[Optional]`: Project ID (leave empty to create a new project).
  - `--group-id <groupId>` `[Optional]`: Group ID (defaults to primary group).
  - `--main-locale <locale>` `[Optional, default: en]`: Main source locale (English `en` is preferred when creating projects).
  - `--target-locales <l1,l2>` `[Optional]`: Comma-separated target locale IDs (e.g. `es,de,fr`).
  - `--description <desc>` `[Optional]`: Project description.
  - `--ignore-words <w1,w2>` `[Optional]`: Comma-separated words to ignore during validation.
  - `--variants <v1,v2>` `[Optional]`: Comma-separated project variants (e.g. `android,ios,web`).
  - `--export-dart` / `--no-export-dart` `[Optional, default: true]`: Enable/disable pure Dart exports.
  - `--export-flutter` / `--no-export-flutter` `[Optional, default: true]`: Enable/disable Flutter exports.
  - `--validate-export` / `--no-validate-export` `[Optional, default: true]`: Validate export before compilation.
- `localizable project delete --id <projectId>`:
  - `--id <projectId>` `[Required]`: Project ID to delete.
- `localizable project config [--project-id <id>] [--path <dir>] [--save]`:
  - `--project-id <id>` `[Optional]`: Project ID (defaults to ID from `localizable_project.json`).
  - `--path <dir>` `[Optional, default: .]`: Directory to save `localizable_project.json`.
  - `--save` `[Optional]`: Flag to save config directly to disk.
- `localizable project import --group-id <groupId> --name <name> --data <dataOrFile>`:
  - `--group-id <groupId>` `[Required]`: Target Group ID.
  - `--name <name>` `[Required]`: Imported project name.
  - `--data <dataOrFile>` `[Required]`: JSON backup string or path to backup JSON file.

#### `localizable locale`
- `localizable locale list`: List all supported locales with metadata.
- `localizable locale get --id <localeId>`:
  - `--id <localeId>` `[Required]`: Locale code (e.g. `en`, `nl`, `es-ES`).

#### `localizable translation`
- `localizable translation list [--project-id <id>]`:
  - `--project-id <id>` `[Optional]`: Target project ID (defaults to ID from `localizable_project.json`).
- `localizable translation search --query <term> [--project-id <id>]`:
  - `-q, --query <term>` `[Required]`: Search term / keyword.
  - `--project-id <id>` `[Optional]`: Target project ID (defaults to ID from `localizable_project.json`).
- `localizable translation get --id <translationId>`:
  - `--id <translationId>` `[Required]`: Translation key ID.
- `localizable translation upsert --key <key> [--id <id>] [--project-id <id>]`:
  - `-k, --key <key>` `[Required]`: Translation key name in **`snake_case`** (lowercase letters `a-z` and `_` only, no digits).
  - `--id <id>` `[Optional]`: Translation key ID (leave empty to create a new key).
  - `--project-id <id>` `[Optional]`: Target project ID (defaults to ID from `localizable_project.json`).
  *Important: Creating a translation key only registers the key identifier. You MUST immediately call `localizable localization upsert` to populate the main localization text (preferred English `en`).*
- `localizable translation copy --id <id> --key <newKey> [--project-id <id>]`:
  - `--id <id>` `[Required]`: Source translation ID to duplicate.
  - `-k, --key <newKey>` `[Required]`: New translation key name in **`snake_case`** (no digits).
  - `--project-id <id>` `[Optional]`: Target project ID (defaults to source project if omitted).
- `localizable translation delete --id <translationId>`:
  - `--id <translationId>` `[Required]`: Translation key ID to delete.

#### `localizable localization`
- `localizable localization list --translation-id <id>`:
  - `--translation-id <id>` `[Required]`: Translation key ID.
- `localizable localization get --id <id>`:
  - `--id <id>` `[Required]`: Localization ID.
- `localizable localization find --translation-id <id> --locale-id <locale> [--variant <variant>]`:
  - `--translation-id <id>` `[Required]`: Translation key ID.
  - `--locale-id <locale>` `[Required]`: Locale code (e.g. `en`, `nl`, `es`).
  - `--variant <variant>` `[Optional]`: Variant name (e.g. `android`, `ios`). Defaults to NULL (general translation).
- `localizable localization upsert --translation-id <id> --locale-id <locale> --text <text> [options]`:
  - `--translation-id <id>` `[Required]`: Translation key ID.
  - `--locale-id <locale>` `[Required]`: Locale code (e.g. `en`, `nl`, `de`).
  - `-t, --text <text>` `[Required]`: Localized text string value.
  - `--id <id>` `[Optional]`: Localization ID (leave empty to create a new entry or auto-update existing entry for the given translation, locale, and variant).
  - `--variant <variant>` `[Optional]`: Variant name. Defaults to NULL.
  - `--auto-translate` `[Optional]`: Flag to trigger auto-translation to other target locales (preferably excluded in CLI commands; target locales are automatically updated when the main language is upserted if auto-translate is enabled at the project level).
  *Important: Every translation key requires at least the main localization text (preferred English `en`).*
- `localizable localization upsert-batch --data <dataOrFile>`:
  - `-d, --data <dataOrFile>` `[Required]`: JSON array string or path to JSON file containing localizations.
- `localizable localization delete --id <id>`:
  - `--id <id>` `[Required]`: Localization ID to delete.

#### `localizable variable`
- `localizable variable list --translation-id <id>`:
  - `--translation-id <id>` `[Required]`: Translation key ID.
- `localizable variable get --id <id>`:
  - `--id <id>` `[Required]`: Variable ID.
- `localizable variable upsert --translation-id <id> --name <name> [options]`:
  - `--translation-id <id>` `[Required]`: Translation key ID.
  - `-n, --name <name>` `[Required]`: Variable identifier in **`camelCase`** (letters only, no digits).
  - `-f, --format <format>` `[Optional, default: text]`: Variable format (`text`, `number`, `measurement`, `date`, `gender`, `plural`, `static`, `custom`).
  - `-p, --position <index>` `[Optional, default: 0]`: Zero-based argument position.
  - `--custom-fields <f1,f2>` `[Optional]`: Comma-separated custom field names (for `custom` format).
  - `--id <id>` `[Optional]`: Variable ID (leave empty to create a new variable).
- `localizable variable delete --id <id>`:
  - `--id <id>` `[Required]`: Variable ID to delete.

#### `localizable variable-localization`
- `localizable variable-localization list --variable-id <id>`:
  - `--variable-id <id>` `[Required]`: Variable ID.
- `localizable variable-localization get --id <id>`:
  - `--id <id>` `[Required]`: Variable localization ID.
- `localizable variable-localization find --variable-id <id> --locale-id <locale> --field <field> [--variant <variant>]`:
  - `--variable-id <id>` `[Required]`: Variable ID.
  - `--locale-id <locale>` `[Required]`: Locale code (e.g. `en`, `nl`).
  - `--field <field>` `[Required]`: Plural or gender category (`zero`, `one`, `two`, `few`, `many`, `other`, `male`, `female`).
  - `--variant <variant>` `[Optional]`: Variant name. Defaults to NULL.
- `localizable variable-localization upsert --variable-id <id> --locale-id <locale> --field <field> --text <text> [options]`:
  - `--variable-id <id>` `[Required]`: Variable ID.
  - `--locale-id <locale>` `[Required]`: Locale code (e.g. `en`, `nl`).
  - `--field <field>` `[Required]`: Plural or gender category (`zero`, `one`, `two`, `few`, `many`, `other`, `male`, `female`).
  - `-t, --text <text>` `[Required]`: Localized replacement template (e.g. `${value} unread messages`).
  - `--id <id>` `[Optional]`: Variable localization ID (leave empty to create a new entry or auto-update existing entry for the given variable, locale, field, and variant).
  - `--variant <variant>` `[Optional]`: Variant name. Defaults to NULL.
  - `--auto-translate` `[Optional]`: Flag to trigger auto-translation to other locales (preferably excluded in CLI commands; target locales are automatically updated when the main language is upserted if auto-translate is enabled at the project level).
- `localizable variable-localization upsert-batch --data <dataOrFile>`:
  - `-d, --data <dataOrFile>` `[Required]`: JSON array string or path to JSON file.
- `localizable variable-localization delete --id <id>`:
  - `--id <id>` `[Required]`: Variable localization ID to delete.

#### `localizable tag`
- `localizable tag list-by-project [--project-id <id>]`:
  - `--project-id <id>` `[Optional]`: Target project ID (defaults to ID from `localizable_project.json`).
- `localizable tag list-by-translation --translation-id <id>`:
  - `--translation-id <id>` `[Required]`: Translation key ID.
- `localizable tag get --id <id>`:
  - `--id <id>` `[Required]`: Tag ID.
- `localizable tag upsert --name <name> [--id <id>] [--project-id <id>] [--translation-ids <id1,id2>]`:
  - `-n, --name <name>` `[Required]`: Tag name (e.g. `auth`, `checkout`, `settings`).
  - `--id <id>` `[Optional]`: Tag ID (leave empty to create a new tag).
  - `--project-id <id>` `[Optional]`: Target project ID (defaults to ID from `localizable_project.json`).
  - `--translation-ids <id1,id2>` `[Optional]`: Comma-separated translation IDs to associate.
- `localizable tag delete --id <id>`:
  - `--id <id>` `[Required]`: Tag ID to delete.
- `localizable tag add-translation --tag-id <tagId> --translation-id <translationId>`:
  - `--tag-id <tagId>` `[Required]`: Tag ID.
  - `--translation-id <translationId>` `[Required]`: Translation ID.
- `localizable tag remove-translation --tag-id <tagId> --translation-id <translationId>`:
  - `--tag-id <tagId>` `[Required]`: Tag ID.
  - `--translation-id <translationId>` `[Required]`: Translation ID.

#### `localizable translate`
- `localizable translate --source-locale <src> --target-locale <target> --text <text> [options]`:
  - `-t, --text <text>` `[Required]`: Text string to translate.
  - `-s, --source-locale <src>` `[Required]`: Source locale code (e.g. `en`).
  - `--target-locale <target>` `[Required]`: Target locale code (e.g. `es`, `fr`, `de`, `nl`).
  - `--project-id <id>` `[Optional]`: Target project ID.
  - `--translation-loc-id <id>` `[Optional]`: Translation localization ID context for enhanced AI accuracy.
  - `--variable-loc-id <id>` `[Optional]`: Variable localization ID context.
  - `--field-name <name>` `[Optional]`: Field name context.

#### `localizable issue`
- `localizable issue list-by-project [--project-id <id>]`:
  - `--project-id <id>` `[Optional]`: Target project ID (defaults to ID from `localizable_project.json`).
- `localizable issue list-by-translation --translation-id <id>`:
  - `--translation-id <id>` `[Required]`: Translation key ID.

---

## 6. Troubleshooting & Best Practices for Agents

- **Always Populate Main Localization Text First (Exclude `--auto-translate` in CLI):** Creating a translation key (`localizable translation upsert`) only registers an empty key identifier. Agents must **NEVER** stop after creating a key — always immediately call `localizable localization upsert` to fill in the main localization text (preferred English `en`) without the `--auto-translate` CLI parameter (`--auto-translate` should preferably be excluded in CLI commands). When the main language is upserted, target languages are automatically updated when auto-translate is set to enabled on the project level. Only set localization text for a target language when auto-translate is not set to enabled on the project level (or when custom manual translation overrides are needed).
- **Preferred English Main Locale:** When creating a new project (`localizable project upsert`), always prefer English (`--main-locale "en"`) as the source/main language.
- **Preferred Flutter Widget Pattern:** In Flutter widgets, the preferred method is defining `final localizable = Localizable.of(context);` at the beginning of the `build` method and referencing `localizable.<key>(...)` rather than repeating `Localizable.of(context)` inline.
- **Translation Key Naming Rules:** Translation keys must always use **`snake_case`** and contain only lowercase letters (`a-z`) and underscores (`_`). Numbers (`0-9`) are strictly not allowed.
- **Variable Naming Rules:** Variable names must always use **`camelCase`** and contain only letters (`a-z`, `A-Z`). Numbers (`0-9`) are strictly not allowed.
- **Always use `--json`**: Enables clean programmatic parsing of responses.
- **Re-run `localizable update`**: Always run `localizable update` after modifying translations, keys, or variables remotely to regenerate local Dart/Flutter files.
- **Check exit codes**: Success returns exit code `0`, failure returns `1` (or `64` for usage errors) with `{"error": "..."}` JSON payload.
- **Automatic Project ID Resolution:** In commands that require a Project ID (`translation`, `tag`, `issue`), the CLI resolves the Project ID in the following order:
  1. Explicit `--project-id <id>` CLI argument.
  2. `localizable_project.json` in the current directory or any parent directory.
  3. Environment variable `LOCALIZABLE_PROJECT_CONFIG` or `LOCALIZABLE_PROJECT_KEY`.
  4. Automatic resolution from the authenticated user account (when only one project exists).
  If multiple projects exist and no `localizable_project.json` is found, provide `--project-id <id>` or run `localizable project config --project-id <id> --save`.
''';