fluffychat/scripts/FIND_UNUSED_INTL_KEYS.md

Find Unused Translation Keys Script

This Python script helps identify unused translation keys in the intl_en.arb file that are not referenced anywhere in the codebase.

Purpose

The script was created to clean up the internationalization (i18n) files by finding translation keys that are defined but never used. This helps maintain a cleaner codebase and reduces translation overhead.

How It Works

1. Extracts Keys: Reads lib/l10n/intl_en.arb and extracts all translation keys after line 3243 (configurable)
2. Filters Metadata: Automatically excludes keys starting with @ (metadata keys)
3. Filters Placeholders: Excludes nested placeholder keys inside metadata objects (e.g., l1, l2, type, placeholders)
4. Searches Repository: Uses git grep to efficiently search for each key in the repository
5. Filters Results: Excludes matches found only in .arb files (other language files)
6. Reports Findings: Generates a JSON file with the list of unused keys

Usage

# Run from repository root
python3 scripts/find_unused_intl_keys.py

Output

The script provides two types of output:

1. Console Output: Real-time progress and summary of findings
2. JSON File: List of unused keys saved to scripts/unused_intl_keys.json

Sample Console Output

Extracting keys from /path/to/intl_en.arb after line 3243...
Found 1869 translation keys to check.

Searching repository for key references...
  Checked 10/1869 keys...
  ...
  
Search complete!
Total keys checked: 1869
Used keys: 1381
Unused keys: 488

================================================================================
RESULTS
================================================================================

Found 488 unused keys (not referenced in any .dart files):
--------------------------------------------------------------------------------
  - aaDisplayName
  - abDisplayName
  - acceptSelection
  ...

Sample JSON Output

{
  "unused_keys": [
    "aaDisplayName",
    "abDisplayName",
    "acceptSelection",
    ...
  ],
  "count": 488,
  "source_file": "/path/to/lib/l10n/intl_en.arb",
  "start_line": 3243
}

Understanding the Results

• Unused keys: Translation keys that appear only in .arb files and nowhere else in the codebase
• Metadata keys (starting with @) are automatically excluded from the analysis
• Placeholder keys (nested inside metadata objects like placeholders) are automatically excluded

Notes

• Keys starting with @ are metadata and are automatically skipped
• Nested keys inside metadata objects (like l1, l2 in placeholders) are automatically filtered out
• Only top-level translation keys are analyzed
• The script searches only for exact key matches in the repository
• False positives are possible if keys are constructed dynamically (e.g., using string interpolation)
• Always review the unused keys list before removing them from the translation files

Customization

To check from a different line number, modify the start_line parameter in the main() function:

unused_keys = find_unused_keys(str(arb_file_path), str(repo_path), start_line=3243)

Requirements

• Python 3.x
• Git (for git grep command)
• Repository must be a git repository

Next Steps

After identifying unused keys:

1. Review the unused keys list in scripts/unused_intl_keys.json
2. Determine which keys can be safely removed
3. Remove unused keys from intl_en.arb
4. Run the script again to verify
5. Consider removing the same keys from other language .arb files

Related Files

• Source translation file: lib/l10n/intl_en.arb
• Other language files: lib/l10n/intl_*.arb
• Generated JSON output: scripts/unused_intl_keys.json