Skip to content

User Guide

Jump to bottom
Alp Yalay edited this page Jan 3, 2026 · 2 revisions

User Guide

This guide covers the essential workflows of LocalizerAppMain. All descriptions are based on the actual application code.

Table of Contents

  1. Getting Started
  2. Main Views
  3. Basic Comparison
  4. Advanced Diff View
  5. Batch Processing (Files View)
  6. History
  7. Quality Dashboard
  8. Settings
  9. Keyboard Shortcuts

Getting Started

  1. Launch the application (LocalizerAppMain.exe or flutter run).
  2. The app defaults to the Basic Comparison view.
  3. The theme (Light, Dark, Amoled) is set to follow your system preference by default. You can change it in Settings > Appearance.

Main Views

The application is organized into several views accessible via the navigation rail on the left:

View Purpose
Basic Comparison Compare two files, see results, filter by status.
Advanced Diff Detailed, row-by-row diff table with editing and AI features.
Files Compare entire directories (batch processing).
History Browse and reload past comparison sessions.
Quality Dashboard Analytics and metrics for your translation progress.
Settings Configure application preferences.

Basic Comparison

This is the primary view for comparing two localization files.

Selecting Files

There are two ways to select files:

  1. Drag & Drop: Drag a file from your file explorer and drop it onto the "Source" or "Target" drop zones.
  2. Browse: Click the folder icon on a drop zone to open a file picker dialog.

Starting a Comparison

Once both a source and a target file are selected:

  1. Click the Compare Files button.
  2. A progress indicator shows the parsing and diffing stages.
  3. Results appear below, categorized as:
    • Added: Keys in the source file that are missing in the target.
    • Removed: Keys in the target file that are missing in the source.
    • Modified: Keys present in both, but with different values.
    • Identical: Keys where the source and target values match exactly.

Filtering Results

Use the filter buttons above the results list to show/hide specific categories:

  • All | Added | Removed | Modified | Problems

The Problems filter highlights potential issues, such as:

  • Placeholder/variable mismatches (e.g., {name} in source but not in target).
  • Empty target values.

Exporting Results

  1. Click the Export button (download icon) in the results area.
  2. Choose a format: CSV, JSON, or XLSX.
  3. Select a save location. A toast notification will appear with an "Open" button to view the file.

Auto-Reload (File Watching)

When enabled in Settings, the app automatically re-runs the comparison if either the source or target file is modified on disk. This is useful for active development workflows.

Advanced Diff View

After running a comparison in the Basic View, click View Details or navigate to the Advanced tab to open a more detailed analysis.

Layout

  • Main Table (Center): A scrollable, row-by-row list of all entries. Each row shows the Key, Source Value, and Target Value.
  • Sidebar (Right): Contains analytics and, if configured, AI translation tools.

Features

  • Filtering & Sorting: Filter by status (Added, Removed, Modified) and sort by key or similarity.
  • Search: Use the search bar to quickly find specific keys or values.
  • In-line Editing: If enabled in settings, you can click on a target value cell to edit it directly.
  • AI Actions (Sidebar): If an AI provider is configured (e.g., Gemini API key), you can select rows and use AI to:
    • Translate missing entries.
    • Suggest rephrased text.
  • Save Changes: After making edits, click Save to write changes back to the target file.
  • Export: Export the diff results to a file.

Batch Processing (Files View)

Use the Files view to compare all matching files between two directories.

Workflow

  1. Select Directories: Drag-and-drop or browse to select a Source Directory and a Target Directory.
  2. Auto-Matching: The app automatically pairs files with the same name (e.g., en.json in Source with en.json in Target).
  3. Unmatched Files: Files unique to the source or target are listed separately. You can manually pair them using the Match button.
  4. Compare All: Click the Compare All button to run a diff on every paired file.
  5. View Results: The view updates to show a summary for each file pair (e.g., "+5 Added", "-2 Removed").
  • Click on a file pair card to open a detailed dialog with the specific keys that changed.
  1. Export All: Click Export All to generate individual CSV files for each comparison, plus a summary CSV.

History

The History view shows all past comparison sessions.

Browsing History

  • Sessions are displayed as cards, grouped by date.
  • Each card shows: file paths, timestamp, and a mini-chart of Added/Removed/Modified counts.

Sorting & Filtering

  • Sort: Click the sort menu to order by Date, File Path, or Change Count.
  • Search: Use the search bar to filter history by file name.

Actions

  • Reload: Click a history card to reload the comparison into the Basic View with the original files.
  • Delete: Click the trash icon on a card to remove that session from history.
  • Clear All: Click "Clear History" to remove all sessions (with confirmation).

Quality Dashboard

The Quality Dashboard provides an overview of your localization health based on your comparison history.

Metrics & Charts

  • Summary Cards: Shows aggregate stats like Total Sessions, Total Keys Compared, Total Keys Added/Removed/Modified.
  • AI Usage Section: If you use AI translation, this section displays:
    • Total API calls per provider (Gemini, OpenAI, DeepL).
    • Token usage breakdown (Input vs. Output tokens).
    • Estimated cost.
  • Coverage Section: Visual progress bars showing how much of your source content has been translated.
  • Trend Charts: Line charts showing changes over time (Words translated, Coverage %).

Export Report

Click Export Report to generate a full quality report in JSON or Markdown format.

Settings

The Settings view is organized into several sections:

Section Key Options
General Default language, view on startup.
Comparison Engine Comparison mode (Key-based, Order-based, Smart Match), Similarity Threshold, Ignore Case, Ignore Whitespace, Ignore Patterns (Regex).
Appearance Theme (Light, Dark, Amoled), Accent Color, Diff Colors, Font Size/Family.
File Handling Default Encodings (UTF-8, etc.), CSV Delimiter, Auto-Reload on Change.
AI Services API Keys (Gemini, OpenAI, DeepL), Default Model, Temperature, Max Tokens.
Version History (Git) Enable Git integration (stubbed), default branch, commit message template.
About Version info, check for updates.

Saving Settings

All settings changes are saved automatically using Hive persistence.

Keyboard Shortcuts

The application supports several keyboard shortcuts for faster navigation:

Action Shortcut
Open Files... Ctrl+O
Export Results Ctrl+E
Save Changes (Advanced View) Ctrl+S
Refresh / Re-compare Ctrl+R
Focus Search Ctrl+F or /

Localization Comparison Tool — Made with ❤️ using Flutter

Copyright © 2025 Alp Yalay (@KhazP)

Report an Issue • Releases

📖 Documentation

🔗 Links

Clone this wiki locally