Skip to content

dashboard.md

Latest commit

 

History

History
151 lines (119 loc) · 6.62 KB

dashboard.md

File metadata and controls

151 lines (119 loc) · 6.62 KB

Translations Dashboard Guide

The Translations Dashboard is a production-grade, self-contained HTML dashboard for managing, validating, importing, and exporting translation data. It is generated via the locale-sync dashboard CLI command.

Quick Start

# Generate and open the dashboard
locale-sync dashboard ./locales

# Generate without opening in browser
locale-sync dashboard ./locales --no-open

# Custom output path
locale-sync dashboard ./locales --output report.html

# Specify source locale
locale-sync dashboard ./locales --source en

CLI Options

Option Short Description
directory Path to locale directory (auto-discovered if not found)
--source -s Source locale code (e.g., en). Auto-detected if not specified
--output -o Output HTML file path. Defaults to translations-dashboard.html in CWD
--open/--no-open Open in browser after generation (default: open)

Supported Import/Export Formats

JSON

Single-locale structure:

{
  "auth": {
    "login": {
      "title": "Sign In",
      "button": "Log In"
    }
  },
  "common": {
    "save": "Save",
    "cancel": "Cancel"
  }
}

Multi-locale structure:

{
  "en": {
    "auth": { "login": "Sign In" }
  },
  "de": {
    "auth": { "login": "Anmelden" }
  }
}

CSV

key,locale,value
auth.login.title,en,Sign In
auth.login.button,en,Log In
common.save,en,Save
common.cancel,en,Cancel

Required columns: key, value Optional columns: locale, namespace, description, context

Schema & Validation Rules

Rule Severity
Locale codes must match BCP-47 pattern (e.g., en, en-US, zh-Hans-CN) Error
Translation keys use dot notation (e.g., auth.login.title) Error
Key segments must start with a letter or underscore Error
Duplicate keys within a locale Error
Placeholder mismatch between source and translation Error
Missing keys (in source but not target) Error
Empty values Warning
Extra keys (in target but not source) Warning
Leading/trailing whitespace in values Warning
HTML/script content in values Warning
JSON files must have a root object (not array) Error
CSV files must have key and value columns at minimum Error
Key depth exceeds maximum (10 levels) Warning
Value exceeds maximum length (10,000 characters) Warning
Translation length ≥1.8× source length (overflow risk) Info/Warning/Critical

Locale Readiness Scoring

Each locale receives a readiness score based on:

Component Weight Description
Completeness 50% Percentage of keys that have non-empty translations
Placeholder score 30% Percentage of keys with correct placeholder usage
Quality score 20% Inverse of quality issues (duplicates, orphans, length warnings)

Grades: A (≥90), B (≥80), C (≥70), D (≥60), F (<60)

Release readiness requires: score ≥90% AND 0 missing keys AND 0 placeholder issues.

Review Workflow

Translations can be tracked through a review lifecycle:

State Description
draft Initial state - not yet reviewed
reviewed Reviewed by a team member
approved Approved for release/export
rejected Rejected - needs correction

Review states are stored in browser localStorage since the dashboard is a static HTML file. Bulk actions allow setting review status for multiple translations at once.

Export Formatting Options

Option Formats Values
Structure JSON nested (grouped by locale), flat (key-value pairs)
Pretty print JSON true (indented), false (minified)
Indent JSON 2 or 4 spaces
Sort keys JSON, CSV alphabetical, original
Delimiter CSV , (comma), ; (semicolon), \t (tab), | (pipe)
Include headers CSV true, false
Include metadata CSV true (adds namespace column), false
Include empty Both true, false
Scope: locales Both All or selected locale codes
Scope: namespaces Both All or selected namespaces
Missing only Both Export only missing translation entries
Invalid only Both Export only entries with validation issues

How It Fits Into LocaleSync

The dashboard complements the existing CLI workflow:

locale-sync scan      → discover locale files
locale-sync check     → validate missing/extra/empty keys
locale-sync sync      → fill missing keys with source values
locale-sync translate → fill missing keys with translations
locale-sync dashboard → generate interactive HTML dashboard

The dashboard provides a visual overview of everything the CLI commands report, plus import/export/comparison capabilities for translation management workflows.