Skip to content

README.md

Latest commit

 

History

History
77 lines (50 loc) · 3.46 KB

README.md

File metadata and controls

77 lines (50 loc) · 3.46 KB
Raw

LocalizationGuard

Swift 6.1+ macOS 13+ License: MIT Release

English | 한국어 | 日本語

A Swift build tool plug-in that finds localization gaps and reports them as clickable Xcode warnings.

LocalizationGuard compares user-facing strings in Swift source files with the keys in your String Catalogs. It consists of a small command-line scanner and a build tool plug-in that runs the scanner during builds.

Requirements

  • Swift 6.1 or later
  • macOS 13 or later

Installation

In Xcode, select File → Add Package Dependencies and enter:

https://github.com/dudwntjs/LocalizationGuard

Add LocalizationGuardPlugin to your app target, then confirm that it appears under Build Phases → Run Build Tool Plug-ins.

Rules

  • Missing translation: UI-facing literal missing from a String Catalog
  • String interpolation: Interpolated string requiring localization review
  • Unknown localization key: Unknown explicit localization key
  • Missing language: Missing or empty translation for a target language in a String Catalog
  • Localization summary (note): Scan completion summary

Suppress an intentional finding with:

// localization-guard:disable-next-line
Text(verbatim: "HTTP")

Configuration

Add .localizationguard.json to the root of the project being scanned. If catalogs is empty or omitted, LocalizationGuard discovers all .xcstrings files automatically.

{
  "catalogs": ["Sources/Resources/Localizable.xcstrings"],
  "requiredLanguages": ["ko", "en", "ja"],
  "excludedPaths": ["Tests", "Generated", "PreviewContent", ".build"],
  "ignoredFunctions": ["print", "debugPrint", "fatalError", "os_log"]
}

By default, target languages are inferred independently from the locales present in each catalog. Set requiredLanguages to check an explicit set, including a language with no translations yet. Missing entries and empty or whitespace-only values emit Missing language warnings linked to the catalog. The source language uses the key as a fallback; entries marked shouldTranslate: false or stale are skipped. Existing plural/device variants and substitutions are checked for empty values.

Command-line usage

swift run LocalizationGuardCLI /path/to/your/project

When attached to an Xcode target, the plug-in runs automatically when its inputs change. It prints an Localization summary completion summary so you can verify that the scan ran.

Current limitations

LocalizationGuard currently focuses on projects that use Korean source strings.

General string detection targets strings containing Korean characters. Explicitly supported SwiftUI APIs may be checked regardless of language.

The scanner checks key presence and missing/empty per-language values. It does not judge translation quality, review status, or whether all language-specific plural categories are present. Inferred languages cannot detect a locale absent from the entire catalog; use requiredLanguages for that case.

License

LocalizationGuard is available under the MIT License.