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

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
example-formats		example-formats
example		example
src		src
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.npmignore		.npmignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

bllfoad/zlocalz

Folders and files

Latest commit

History

Repository files navigation