@intlpullhq/cli 0.1.6 → 0.1.8

package/README.md

@@ -19,6 +19,31 @@
 
 ---
 
+## Table of Contents
+
+| Section | Description |
+|---------|-------------|
+| [Features](#features) | Key capabilities of the CLI |
+| [Installation](#installation) | How to install the CLI |
+| [Quick Start](#quick-start) | Get started in 4 commands |
+| [Authentication](#authentication) | Login, API keys, and auth methods |
+| [Commands Reference](#commands-reference) | All available commands |
+| ↳ [Initialize](#initialize-project) | Set up IntlPull in your project |
+| ↳ [Upload / Push](#upload--push) | Upload translation keys |
+| ↳ [Download / Pull](#download--pull) | Download translations |
+| ↳ [Sync](#sync) | One-time sync for CI/CD |
+| ↳ [Listen / Watch](#listen--watch) | Real-time sync during dev |
+| ↳ [Import / Export](#import) | Bulk import/export translations |
+| ↳ [OTA Releases](#ota-releases) | Over-the-air updates |
+| ↳ [Migration](#migration) | Migrate from other platforms |
+| [CI/CD Integration](#cicd-integration) | GitHub Actions, GitLab CI, Docker |
+| [Configuration](#configuration) | Project config and output patterns |
+| ↳ [Output Patterns](#output-patterns-namespace-support) | Namespace file structures |
+| [Tips & Best Practices](#tips--best-practices) | Recommended usage patterns |
+| [Support](#support) | Get help |
+
+---
+
 ## Features
 
 - **Parallel Downloads** - Fetch translations by namespace concurrently for blazing fast syncs
@@ -744,35 +769,102 @@ Created by `intlpull init`, this file configures your project:
   "framework": "next",
   "library": "next-intl",
   "outputDir": "./messages",
+  "output": "messages/[locale]/[namespace].json",
   "sourceLanguage": "en",
   "namespaces": ["common", "admin"]
 }
 ```
 
+### Output Patterns (Namespace Support)
+
+The CLI supports flexible output patterns with placeholders to match any i18n library structure.
+
+**Placeholders:**
+- `[locale]` or `{locale}` - Language code (e.g., `en`, `es`, `zh-CN`)
+- `[namespace]` or `{namespace}` - Namespace name (e.g., `common`, `auth`)
+
+**Common Patterns by Framework:**
+
+| Framework/Library | Pattern | Example Output |
+|------------------|---------|----------------|
+| **next-intl** | `messages/[locale].json` | `messages/en.json` |
+| **next-i18next** | `public/locales/[locale]/[namespace].json` | `public/locales/en/common.json` |
+| **react-i18next** | `public/locales/[locale]/[namespace].json` | `public/locales/en/auth.json` |
+| **i18next** | `locales/[locale]/[namespace].json` | `locales/en/common.json` |
+| **vue-i18n** | `src/locales/[locale].json` | `src/locales/en.json` |
+| **Chrome Extension** | `_locales/[locale]/messages.json` | `_locales/en/messages.json` |
+| **React Native** | `assets/locales/[locale]/[namespace].json` | `assets/locales/en/common.json` |
+
+**Configure via CLI flag:**
+```bash
+# Namespaced output (creates separate files per namespace)
+npx @intlpullhq/cli pull --output "public/locales/[locale]/[namespace].json"
+
+# Flat output (merges all namespaces into one file)
+npx @intlpullhq/cli pull --output "messages/[locale].json"
+
+# Namespace-first structure
+npx @intlpullhq/cli pull --output "locales/[namespace]/[locale].json"
+```
+
+**Configure in `.intlpull.json`:**
+```json
+{
+  "projectId": "proj_xxxx",
+  "output": "public/locales/[locale]/[namespace].json"
+}
+```
+
+**Important:** Ensure your i18n library's configuration matches the output path:
+
+| Library | Config Update Required |
+|---------|----------------------|
+| **next-intl** | Update `src/i18n/request.ts` to load from the correct path |
+| **i18next / react-i18next** | Update `backend.loadPath` in your i18n config |
+| **Chrome Extension** | Must use `_locales/[locale]/messages.json` (Chrome requirement) |
+
 ### Environment Variables
 
 | Variable | Description |
 |----------|-------------|
-| `INTLPULL_API_KEY` | API key for authentication |
-| `INTLPULL_DEBUG` | Enable debug logging |
+| `INTLPULL_API_KEY` | API key for authentication (required) |
+| `INTLPULL_PROJECT_ID` | Default project ID |
+| `INTLPULL_DEBUG` | Enable debug logging (`true`/`false`) |
 
 ---
 
 ## Tips & Best Practices
 
-1. **Use project-scoped API keys** - Auto-detects project ID, no need to specify `--project`
-2. **Enable parallel mode** (default) - Downloads namespaces concurrently for faster syncs
-3. **Use `--quiet` in CI** - Minimal output, machine-friendly
-4. **Use `--dry-run`** - Preview changes before applying
-5. **Set up Git branch detection** - CLI auto-detects git branch for branch workflows
+| Practice | Recommendation |
+|----------|----------------|
+| 🔑 **API Keys** | Use project-scoped keys for auto-detection (no `--project` flag needed) |
+| ⚡ **Parallel Mode** | Enabled by default — downloads namespaces concurrently |
+| 🤫 **CI/CD Output** | Use `--quiet` for minimal, machine-friendly logs |
+| 🔍 **Preview Changes** | Use `--dry-run` before applying destructive operations |
+| 🌿 **Branch Workflows** | CLI auto-detects git branch for branch-based translations |
+| 📦 **Namespace Files** | Use output patterns like `[locale]/[namespace].json` for organized files |
 
 ---
 
 ## Support
 
-- Documentation: [docs.intlpull.com](https://docs.intlpull.com)
-- Email: support@intlpull.com
+| Resource | Link |
+|:---------|:-----|
+| 📚 Documentation | [docs.intlpull.com](https://docs.intlpull.com) |
+| 📧 Email Support | [support@intlpull.com](mailto:support@intlpull.com) |
+| 🐛 GitHub Issues | [github.com/intlpullhq/cli/issues](https://github.com/intlpullhq/cli/issues) |
+| 💬 Discord | [discord.gg/intlpull](https://discord.gg/intlpull) |
 
-## License
+---
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#commands-reference">Commands</a> •
+  <a href="#cicd-integration">CI/CD</a> •
+  <a href="#configuration">Config</a>
+</p>
 
-MIT © [IntlPull](https://intlpull.com)
+<p align="center">
+  MIT © <a href="https://intlpull.com">IntlPull</a>
+</p>