nuxt-i18n-micro-cli

v1.3.0

Published

8 months ago

⚡️ nuxt-i18n-micro-cli CLI Experience

0High
0Medium
0Low

s00d

Nuxt i18n CLI

📖 Introduction

nuxt-i18n-micro-cli is a command-line tool designed to streamline the localization and internationalization process in Nuxt.js projects using the nuxt-i18n module. It provides utilities to extract translation keys from your codebase, manage translation files, synchronize translations across locales, and automate the translation process using external translation services.

This guide will walk you through installing, configuring, and using nuxt-i18n-micro-cli to effectively manage your project's translations.

🔧 Installation and Setup

📦 Installing nuxt-i18n-micro-cli

Install nuxt-i18n-micro-cli globally using npm:

npm install -g nuxt-i18n-micro-cli

This will make the i18n-micro command available globally on your system.

🛠 Initializing in Your Project

After installing, you can run i18n-micro commands in your Nuxt.js project directory.

Ensure that your project is set up with nuxt-i18n and has the necessary configuration in nuxt.config.js.

For detailed documentation and further configuration options, visit the nuxt-i18n-micro CLI guide.

🗂️ Commands and Usage

nuxt-i18n-micro-cli provides several commands to help manage your translations:

extract: Extract translation keys from your codebase.
translate: Automatically translate missing keys using external translation services.
sync: Synchronize translation files across locales.
validate: Validate translation files for missing or extra keys.
stats: Display translation statistics for each locale.
clean: Remove unused translation keys from translation files.
import: Convert PO files back to JSON format.
export: Export translations to PO files for external translation management.
text-to-i18n: Replace text in files with translation references.
format: Format translation files by sorting keys and applying consistent indentation.
backup: Creates password-protected zip archives of translation files for backup purposes.
restore: Restores translation files from a backup archive.
optimize: Optimize translation file structure for performance and maintainability.

Each command can be run using i18n-micro <command>.

📄 Common Arguments

--cwd: Specify the current working directory (defaults to .).
--logLevel: Set the log level (silent, info, verbose).

📋 Commands

text-to-i18n

Description: Replace text in files with translation references

Usage:

i18n-micro text-to-i18n [options]

extract

Description: Extracts translation keys from your codebase and organizes them by scope.

Usage:

i18n-micro extract [options]

Options:

--prod, -p: Run in production mode.

Example:

i18n-micro extract

This command scans your project files, extracts translation keys used in components, pages, layouts, etc., and generates translation files in the specified translation directory (default is locales).

translate

Description: Automatically translates missing or all keys using external translation services.

Usage:

i18n-micro translate [options]

Options:

--translationDir: Directory containing JSON translation files (default: locales).
--service: Translation service to use (e.g., google, deepl, yandex, etc.) (default: google).
--token: API key corresponding to the translation service.
--options: Additional options for the translation service in key:value pairs, separated by commas.
--replace: Translate all keys, replacing existing translations (default: false).

Example:

i18n-micro translate --service deepl --token YOUR_DEEPL_API_KEY

This command translates missing keys in your translation files using the specified translation service and saves the translations in the corresponding files.

sync

Description: Synchronizes translation files across locales, ensuring all locales have the same keys.

Usage:

i18n-micro sync [options]

Options:

--translationDir: Directory containing JSON translation files (default: locales).

Example:

i18n-micro sync

This command synchronizes the translation files based on the reference locale (the first locale specified in your nuxt.config.js), adding missing keys and ensuring consistency.

validate

Description: Validates translation files for missing or extra keys compared to the reference locale.

Usage:

i18n-micro validate [options]

Options:

--translationDir: Directory containing JSON translation files (default: locales).

Example:

i18n-micro validate

This command checks for missing or extra keys in your translation files and reports any discrepancies.

stats

Description: Displays translation statistics for each locale.

Usage:

i18n-micro stats [options]

Options:

--translationDir: Directory containing JSON translation files (default: locales).

Example:

i18n-micro stats

This command shows the number of translated keys and the completion percentage for each locale compared to the reference locale.

clean

Description: Removes unused translation keys from translation files.

Usage:

i18n-micro clean [options]

Options:

--translationDir: Directory containing JSON translation files (default: locales).

Example:

i18n-micro clean

This command removes translation keys that are no longer used in your codebase from the translation files.

import

Description: Converts PO files back to JSON format and saves them in the translation directory.

Usage:

i18n-micro import [options]

Options:

--potsDir: Directory containing PO files (default: pots).
--translationDir: Directory to save JSON translation files (default: locales).

Example:

i18n-micro import --potsDir pots --translationDir locales

This command converts PO files to JSON and saves them in the specified translation directory.

export

Description: Exports translations to PO files for external translation management.

Usage:

i18n-micro export [options]

Options:

--potsDir: Directory to save PO files (default: pots).
--translationDir: Directory containing JSON translation files (default: locales).

Example:

i18n-micro export --potsDir pots

This command converts your JSON translation files to PO files, which can be used with external translation tools.

split

Description: Splits large translation files into smaller ones based on various criteria.

Usage:

i18n-micro split [options]

Options:

--translationDir <dir>: Directory containing translation files (default: 'locales')
--maxKeys <number>: Maximum number of keys per file when splitting by key count
--maxDepth <number>: Maximum nesting depth when splitting by depth
--splitByPrefix: Split translations by their prefix (e.g., 'common', 'header', etc.)
--outputDir <dir>: Directory where split files will be saved (default: 'locales/split')
--backup: Create backup of original files before splitting
--cwd <dir>: Current working directory
--logLevel <level>: Logging level (default: 'info')

Features:

Split by Key Count: Divides translations into smaller files based on the maximum number of keys
Split by Depth: Separates translations based on their nesting depth
Split by Prefix: Groups translations by their prefix (e.g., 'common', 'header', etc.)
Combined Splitting: Can combine multiple splitting strategies
Backup Support: Creates backup of original files before splitting

Examples:

Split translations into files with maximum 50 keys each:

i18n-micro split --maxKeys 50

Split translations by depth, keeping maximum 2 levels of nesting:

i18n-micro split --maxDepth 2

Split translations by their prefixes (e.g., 'common', 'header', etc.):

i18n-micro split --splitByPrefix

Combine multiple splitting strategies with backup:

i18n-micro split --maxKeys 50 --maxDepth 2 --splitByPrefix --backup

Specify custom output directory:

i18n-micro split --outputDir locales/modules

format

Description: Formats translation files by sorting keys and applying consistent indentation.

Usage:

i18n-micro format [options]

Options:

--translationDir <dir>: Directory containing translation files (default: 'locales')
--indent <number>: Number of spaces for indentation (default: 2)
--sortKeys: Sort translation keys alphabetically (default: true)
--backup: Create backup before formatting
--cwd <dir>: Current working directory
--logLevel <level>: Logging level (default: 'info')

Features:

Sort by Key: Sorts translation keys alphabetically
Indentation: Applies consistent indentation
Backup: Creates backup before formatting
Multiple Locales: Supports multiple locales
Nested Structure: Preserves nested translation structures

Examples:

Format all translation files with default settings:

i18n-micro format

Format with custom indentation and create backup:

i18n-micro format --indent 4 --backup

Format without sorting keys:

i18n-micro format --sortKeys false

Format specific translation directory:

i18n-micro format --translationDir locales/custom

backup

Description: Creates password-protected zip archives of translation files for backup purposes.

Usage:

i18n-micro backup [options]

Options:

--translationDir <dir>: Directory containing JSON translation files (default: 'locales')
--backupDir <dir>: Directory to save backup archives (default: 'locales/backups')
--password <string>: Password for encrypting the backup archive
--comment <string>: Optional comment to add to backup name
--cwd <dir>: Current working directory
--logLevel <level>: Logging level (default: 'info')

Features:

Password Protection: Creates encrypted zip archives for secure backups
Automatic Naming: Generates unique backup names using timestamps
Custom Comments: Allows adding descriptive comments to backup names
Directory Structure: Preserves the complete directory structure of translations
Compression: Uses maximum compression to minimize backup size

Examples:

Create a basic backup:

i18n-micro backup

Create an encrypted backup with password:

i18n-micro backup --password "your-secure-password"

Create a backup with a descriptive comment:

i18n-micro backup --comment "before-major-update"

Specify custom backup directory:

i18n-micro backup --backupDir "backups/translations"

restore

Description: Restores translation files from a backup archive.

Usage:

i18n-micro restore [options]

Options:

--translationDir <dir>: Directory to restore translation files to (default: 'locales')
--backupDir <dir>: Directory containing backup archives (default: 'locales/backups')
--backup <name>: Name of the backup to restore (optional)
--password <string>: Password for decrypting the backup archive
--force: Skip confirmation prompt
--cwd <dir>: Current working directory
--logLevel <level>: Logging level (default: 'info')

Features:

Password Protection: Supports restoring from encrypted backups
Interactive Selection: Lists available backups if none specified
Confirmation: Requires confirmation before restoring (can be skipped with --force)
Directory Structure: Preserves the complete directory structure of translations
Cleanup: Automatically cleans up temporary files after restoration

Examples:

List available backups:

i18n-micro restore

Restore from a specific backup:

i18n-micro restore --backup "2024-03-20T12-00-00"

Restore from an encrypted backup:

i18n-micro restore --backup "2024-03-20T12-00-00" --password "your-secure-password"

Restore without confirmation:

i18n-micro restore --backup "2024-03-20T12-00-00" --force

optimize

Description: Optimizes translation file structure for performance and maintainability.

Usage:

i18n-micro optimize [options]

Options:

--translationDir: Directory containing JSON translation files (default: 'locales')
--minSize: Minimum file size in bytes for optimization (default: 1024)
--maxDepth: Maximum nesting depth for optimization (default: 3)
--dryRun: Show recommendations without making changes
--updatePaths: Update translation paths in Vue and JS files (default: true)
--cwd: Current working directory
--logLevel: Logging level

Features:

Analyzes file sizes and splits large files into smaller ones
Optimizes deeply nested keys
Removes duplicate keys
Updates translation paths in Vue and JS files
Preserves translation structure
Interactive mode with confirmation of changes
Dry run mode for preview

Examples:

# Analyze files without making changes
i18n-micro optimize --dryRun

# Optimize with minimum file size of 2KB
i18n-micro optimize --minSize 2048

# Optimize with maximum nesting depth of 2
i18n-micro optimize --maxDepth 2

# Optimize files in specified directory
i18n-micro optimize --translationDir custom/locales

# Optimize without updating paths in Vue and JS files
i18n-micro optimize --updatePaths false

🛠 Examples

Extracting translations:
```
i18n-micro extract
```

Translating missing keys using Google Translate:

i18n-micro translate --service google --token YOUR_GOOGLE_API_KEY

Translating all keys, replacing existing translations:

i18n-micro translate --service deepl --token YOUR_DEEPL_API_KEY --replace

Validating translation files:
```
i18n-micro validate
```
Cleaning unused translation keys:
```
i18n-micro clean
```
Synchronizing translation files:
```
i18n-micro sync
```

⚙️ Configuration Guide

nuxt-i18n-micro-cli relies on your Nuxt.js i18n configuration in nuxt.config.js. Ensure you have the nuxt-i18n module installed and configured.

🔑 nuxt.config.js Example

export default {
  modules: ['@nuxtjs/i18n'],
  i18n: {
    locales: [
      { code: 'en', iso: 'en-US' },
      { code: 'fr', iso: 'fr-FR' },
      { code: 'es', iso: 'es-ES' },
      // Add other locales as needed
    ],
    defaultLocale: 'en',
    vueI18n: {
      fallbackLocale: 'en',
    },
    // Specify the directory where your translation files are stored
    translationDir: 'locales',
  },
};

Ensure that the translationDir matches the directory used by nuxt-i18n-micro-cli (default is locales).

🌐 Supported Translation Services

The translate command supports multiple translation services. Some of the supported services are:

Google Translate (google)
DeepL (deepl)
Yandex Translate (yandex)
OpenAI (openai)
Azure Translator (azure)
IBM Watson (ibm)
Baidu Translate (baidu)
LibreTranslate (libretranslate)
MyMemory (mymemory)
Lingva Translate (lingvatranslate)
Papago (papago)
Tencent Translate (tencent)
Systran Translate (systran)
Yandex Cloud Translate (yandexcloud)
ModernMT (modernmt)
Lilt (lilt)
Unbabel (unbabel)
Reverso Translate (reverso)

⚙️ Service Configuration

Some services require specific configurations or API keys. When using the translate command, you can specify the service and provide the required --token (API key) and additional --options if needed.

For example:

i18n-micro translate --service openai --token YOUR_OPENAI_API_KEY --options openaiModel:gpt-3.5-turbo,max_tokens:1000

📝 Best Practices

🔑 Consistent Key Naming

Ensure translation keys are consistent and descriptive to avoid confusion and duplication.

🧹 Regular Maintenance

Use the clean command regularly to remove unused translation keys and keep your translation files clean.

🛠 Automate Translation Workflow

Integrate nuxt-i18n-micro-cli commands into your development workflow or CI/CD pipeline to automate extraction, translation, validation, and synchronization of translation files.

🛡️ Secure API Keys

When using translation services that require API keys, ensure your keys are kept secure and not committed to version control systems. Consider using environment variables or secure key management solutions.

📞 Support and Contributions

If you encounter issues or have suggestions for improvements, feel free to contribute to the project or open an issue on the project's repository.

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Nuxt i18n CLI

📖 Introduction

🔧 Installation and Setup

📦 Installing nuxt-i18n-micro-cli

🛠 Initializing in Your Project

🗂️ Commands and Usage

📄 Common Arguments

📋 Commands

text-to-i18n

extract

translate

sync

validate

stats

clean

import

export

split

format

backup

restore

optimize

🛠 Examples

⚙️ Configuration Guide

🔑 nuxt.config.js Example

🌐 Supported Translation Services

⚙️ Service Configuration

📝 Best Practices

🔑 Consistent Key Naming

🧹 Regular Maintenance

🛠 Automate Translation Workflow

🛡️ Secure API Keys

📞 Support and Contributions

License