zlocalz

ZLocalz - Universal TUI Locale Guardian

A powerful Terminal User Interface (TUI) application for managing Flutter localization files in multiple formats. ZLocalz supports ARB, JSON, YAML, CSV, and TSV files, ensuring perfect synchronization between your source locale and target translations with automatic validation, fixing, and AI-powered translation capabilities.

Repository: github.com/bllfoad/zlocalz

⚠️ Beta: ZLocalz is currently in beta and may have issues. If you run into problems, please open an issue via the CLI with zlocalz issue --new or visit the issues page at github.com/bllfoad/zlocalz/issues.

Features

📁 Universal Format Support

• ARB Files: Native Flutter Application Resource Bundle support
• JSON Files: Standard JSON localization format
• YAML Files: Hierarchical YAML with metadata support
• CSV/TSV: Multi-locale spreadsheet format for easy editing
• Auto-Detection: Automatically detects and handles mixed formats

🔍 Smart Validation

• Detect missing keys, extra keys, duplicates, ICU errors, placeholder mismatches, and formatting issues
• Format-specific validation rules
• Cross-format compatibility checks

🔧 Intelligent Auto-Fix

• Automatically fix common issues while preserving translations
• Format-aware corrections (JSON, YAML, CSV structure preservation)
• Configurable key ordering (source-mirror or alphabetical)

🤖 AI Translation

• Translate missing keys using Google Gemini with context awareness
• Preserve ICU message format and placeholders
• Domain glossary and style guidelines support

📊 Powerful TUI

• 3-pane interface: file tree, key list, and inspector
• Format-specific syntax highlighting
• Multi-format diff viewer

🎯 Advanced Operations

• Batch operations across multiple formats
• Multi-step undo/redo for safe experimentation
• Export to different formats
• Git integration for change tracking

🔄 Automatic Update System

• Fully Automatic: Updates install automatically for patch/minor releases
• Smart Updates: Major version changes require user confirmation
• Background Process: Updates happen silently without interrupting workflow
• Manual Control: zlocalz update for immediate updates
• Configurable: Disable with "autoUpdate": false in config
• Welcome Messages: Shows what's new after auto-updates

Installation

npm install -g zlocalz

Quick Start

Interactive Setup (Recommended)

Simply run zlocalz without any arguments to launch the interactive setup wizard:

zlocalz

The setup wizard will:

• Detect existing localization files automatically
• Guide you through configuration options
• Create zlocalz.config.json and .env files
• Launch the TUI interface when complete

Manual Configuration

Alternatively, create a configuration file zlocalz.config.json manually:

{
  "flutterLocalesPath": "lib/l10n/",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de"],
  "fileFormat": "auto",
  "autoUpdate": true,
  "doAutoFix": true,
  "translateMissing": true,
  "geminiModel": "gemini-2.5-pro",
  "preferOrder": "mirror-source"
}

Note: autoUpdate defaults to true. Set to false to disable automatic updates and receive notifications instead.

Supported File Formats

ARB (Application Resource Bundle):

lib/l10n/app_en.arb
lib/l10n/app_es.arb

JSON:

locales/en.json
locales/es.json  

YAML:

i18n/en.yml
i18n/es.yml

CSV (Multi-locale in one file):

translations.csv:
key,en,es,fr
welcome,"Welcome!","¡Bienvenido!","Bienvenue!"

• Set your Gemini API key:

export GEMINI_API_KEY="your-api-key"

• Launch ZLocalz:

# Interactive setup (first-time users)
zlocalz

# Auto-detect format and launch TUI
zlocalz scan

# Specify format explicitly  
zlocalz scan --format json
zlocalz scan --format yaml
zlocalz scan --format csv

# Command-line mode
zlocalz scan --no-tui

Setup Wizard Features

The interactive setup wizard (zlocalz without arguments) provides:

🔍 Smart Detection

• Automatically scans common Flutter localization directories (lib/l10n, assets/l10n, etc.)
• Detects existing file formats (ARB, JSON, YAML, CSV, TSV)
• Suggests optimal configuration based on your project structure

⚙️ Configuration Options

• Basic Setup: Path, format, source/target locales
• Advanced Options: Auto-fix settings, key ordering preferences
• AI Translation: Optional Google Gemini integration with API key management
• Format-Specific: CSV delimiter and column configuration

📁 File Management

• Creates zlocalz.config.json with your preferences
• Securely stores API keys in .env file
• Automatically adds .env to .gitignore
• Validates all inputs with helpful error messages

🚀 Seamless Launch

• Automatically launches TUI interface after setup
• Shows configuration summary and next steps
• Provides helpful tips for using ZLocalz effectively

TUI Keybindings

Navigation

• ←/→ - Focus panes
• ↑/↓ - Move selection
• Tab - Cycle panes

Search & Filter

• / - Global search
• f - Filter menu
• * - Toggle "only issues"

Actions

• a - Auto-fix selected
• t - Translate selected
• d - View diff
• e - Edit value
• m - Edit metadata
• Space - Select/deselect key
• A - Select all visible

File Operations

• S - Save changes
• P - Copy patch
• u - Undo
• Ctrl+r - Redo

Commands

• : - Open command palette
• ? - Show help
• q - Quit

CLI Commands

Scan and validate

zlocalz scan --path lib/l10n --source en --targets es fr

Auto-fix issues

zlocalz fix

Translate missing keys

zlocalz translate --key YOUR_GEMINI_API_KEY

Export report

zlocalz scan --no-tui > report.json

Report an issue from the CLI

# Open issues page
zlocalz issue

# Open new issue form
zlocalz issue --new

Configuration

Required Fields

• flutterLocalesPath: Path to your Flutter localization files
• sourceLocale: The reference locale (e.g., "en")
• targetLocales: Array of target locale codes

Optional Fields

• doAutoFix: Enable automatic fixes (default: false)
• translateMissing: Enable AI translation (default: false)
• geminiModel: Gemini model to use (default: "gemini-2.5-pro")
• styleGuidelines: Translation style rules
• domainGlossary: Key-value pairs for consistent translations
• doNotTranslate: Tokens to preserve (e.g., brand names)
• preferOrder: "mirror-source" or "alphabetical"

Example Workflow

• Scan: Open TUI and review validation issues
• Filter: Use f to filter by issue type
• Select: Space to select affected keys
• Fix: Press a to auto-fix selected issues
• Translate: Press t to translate missing keys
• Review: Use diff view (d) to review changes
• Save: Press S to write changes to disk

Output

ZLocalz generates a comprehensive JSON report with:

• Issue summary by type and locale
• Applied fixes with descriptions
• Translation results with safety checks
• Unified diff patches
• Ready-to-commit file contents

Roadmap

• Fix bugs and improve stability across all supported formats
• TUI visual upgrade: modern themes, layout polish, accessibility, and mouse support
• Add new features based on community feedback (filters, reports, bulk ops)
• First-class Next.js support (integrate with Next.js i18n config and file structures)

Collaboration

We are open to collaboration and welcome contributions of all sizes. Ways you can help:

• Improve stability by fixing bugs
• Make the TUI look great with better UX, theming, and accessibility
• Add features that make workflows faster and safer
• Implement and refine Next.js support

How to collaborate:

• Fork the repo: github.com/bllfoad/zlocalz
• Create a branch: git checkout -b feat/your-feature
• Install dependencies: npm install
• Run in dev mode: npm run dev
• Build locally: npm run build
• Lint and test: npm run lint and npm test
• Open a Pull Request with a clear description and screenshots when relevant

For discussions, ideas, or questions, please open an issue in the repository.

License

MIT