Tongues Documentation

Complete guide for i18n translation validation

Getting Started

Tongues is a powerful i18n translation file checker that helps maintain consistency across your translation files. It automatically scans common i18n directories and supports JSON and ARB formats.

Quick Start

go install  github.com/infobits-io/tongues@latest

tongues

Tongues will automatically find your translation files in common directories like i18n, locales, src/i18n, src/locales, and more.

Installation

Go Install

If you have Go installed (1.21 or later):

go install  github.com/infobits-io/tongues@latest

Homebrew (macOS)

Install using Homebrew on macOS:

brew tap infobits/tongues\nbrew install tongues

Snap (Linux)

Install using Snap on Linux distributions:

sudo snap install tongues

Scoop (Windows)

Install using Scoop on Windows:

scoop bucket add infobits https://github.com/infobits/scoop-bucket\nscoop install tongues

Binary Downloads

Download pre-built binaries from the releases page.

CLI Usage

Tongues provides a comprehensive command-line interface with many options.

Basic Usage

tongues

This checks translation files in the current directory or automatically finds them in common i18n directories.

Command Options

-d, --dir <path>

Directory containing translation files (default: ./i18n or auto-detect)

-r, --reference <lang>

Reference language code (default: en)

-f, --format <format>

Output format: text or json (default: text)

--strict

Exit with code 1 if any issues found

--extra

Check for extra keys not in reference

--clean

Clean and sort translation files alphabetically

--fix

Fix missing keys by copying from reference

--placeholder <text>

Add placeholder text for missing/empty keys (e.g., "[TODO]")

--check-descriptions

Check for missing descriptions in ARB files

-v, --verbose

Show detailed output with all missing keys

Examples

# Check translations in current directory
tongues

# Check specific directory
tongues -d ./locales

# Use Spanish as reference
tongues -r es

# Output as JSON for CI/CD
tongues -f json --strict

# Clean and sort files
tongues --clean

# Fix missing keys with placeholder
tongues --fix --placeholder "[TODO]"

# Check ARB descriptions
tongues --check-descriptions

# Verbose output with extra keys
tongues -v --extra

GitHub Action

Tongues provides a reusable GitHub Action for CI/CD pipelines.

Basic Setup

name: Check Translations
on: [push, pull_request]

jobs:
  i18n-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: infobits/tongues@v1
        with:
          directory: ./i18n
          strict: true

Advanced Configuration

name: i18n Validation
on:
  pull_request:
    paths:
      - 'locales/**'
      - 'src/i18n/**'

jobs:
  validate-translations:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Check Translations
        uses: infobits/tongues@v1
        with:
          directory: ./src/i18n
          reference: en
          strict: true
          check-empty: true
          check-extra: true
          check-descriptions: true
      
      - name: Auto-fix Missing Keys
        if: github.event_name == 'pull_request'
        uses: infobits/tongues@v1
        with:
          directory: ./src/i18n
          fix: true
          placeholder: '[TODO]'
      
      - name: Commit fixes
        if: github.event_name == 'pull_request'
        run: |
          git config --local user.email "[email protected]"
          git config --local user.name "GitHub Action"
          git add .
          git diff --staged --quiet || git commit -m "Auto-fix missing translations"
          git push

Features

Automatic Directory Detection

Tongues automatically searches for translation files in common directories:

i18n/
l10n/
locales/
translations/
lang/
src/i18n/
src/l10n/
src/locales/
src/translations/
src/lang/

Nested Key Support

Tongues flattens nested JSON structures for comprehensive checking:

{
  "user": {
    "profile": {
      "name": "Name",
      "email": "Email"
    }
  }
}
// Checked as: user.profile.name, user.profile.email

Smart Filename Detection

Recognizes various naming patterns:

en.json - Simple language code
en_US.json - Locale with region
app_en.arb - Prefixed filenames
messages_es.json - Named bundles

ARB Format Support

Full support for Flutter's ARB format including:

Automatic locale detection from @@locale
Description checking with @key metadata
Placeholder validation

File Cleaning & Sorting

Keep your translation files organized:

Alphabetically sort keys
Maintain consistent formatting
Remove duplicate keys
Preserve metadata in ARB files

Auto-fix Capabilities

Automatically repair common issues:

Add missing keys from reference
Insert placeholder text for TODO items
Copy translations from reference language
Clean and standardize file structure

API Reference

Coming soon: REST API for translation validation and auto-translation services.

Authentication

The API supports multiple authentication methods:

API Keys for CLI and CI/CD
JWT tokens for web applications
GitHub OAuth for repository integration

Endpoints

POST /api/v1/translate
{
  "source_language": "en",
  "target_language": "es",
  "text": "Hello, world!",
  "project_id": "uuid"
}

GET /api/v1/translate/usage
{
  "tokens_used": 15000,
  "translations_count": 250,
  "period": "2024-01"
}

POST /api/v1/projects
{
  "name": "my-app",
  "github_repo": "user/repo",
  "settings": {
    "auto_translate": true,
    "reference_language": "en"
  }
}

CLI Authentication

# Login to Tongues service
tongues auth login

# Set API key
export TONGUES_API_KEY="your-api-key"

# Use with auto-translation
tongues --fix --auto-translate