Metadata-Version: 2.4
Name: i18n-security-lint
Version: 0.2.1
Summary: Scans locale files for translated-string security defects: Unicode bidi misuse, XSS payloads, and format/interpolation placeholder drift.
Author: OSS Infrastructure Initiative
License: Apache-2.0
Project-URL: Homepage, https://github.com/ecogetaway/oss-language-inclusion/tree/main/tools/i18n-security-lint
Project-URL: Repository, https://github.com/ecogetaway/oss-language-inclusion
Project-URL: Issues, https://github.com/ecogetaway/oss-language-inclusion/issues
Project-URL: Security, https://github.com/ecogetaway/oss-language-inclusion/blob/main/SECURITY.md
Keywords: i18n,l10n,security,linter,locale,translations,bidi,trojan-source,xss,gettext,xliff,fluent
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Internationalization
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# i18n-security-lint

A command-line tool and CI action that scans locale files for security defects
introduced through unreviewed translated strings.

It checks the four vulnerability classes documented in the parent repository's
[Security Scope](https://github.com/ecogetaway/oss-language-inclusion#security-scope):

1. **Bidirectional control misuse** — overrides (`U+202D`, `U+202E`) that make
   displayed text differ from actual file content, and controls left
   unterminated so they leak direction into surrounding UI. Balanced isolates
   (`U+2066`–`U+2069`) are the mechanism Unicode and W3C recommend and are
   **not** reported.
2. **Cross-site scripting (XSS) in rendered locale content** — HTML/script
   fragments embedded in translated strings.
3. **Format-specifier tampering** — printf-family specifiers (`%s`, `%d`,
   `%1$d`, `%(name)s`) added, removed, or retyped during translation.
4. **Interpolation-variable integrity failures** — brace- and template-style
   variables (`{0}`, `{name}`, `{{var}}`, `$t(key)`) renamed or omitted,
   breaking string interpolation.

Full rule ids, severities, and detection methods are specified in
[`spec/translated-string-security-checks.md`](../../spec/translated-string-security-checks.md).

## Supported formats

| Format | Extension | Source pair used for checks 3–4 |
| --- | --- | --- |
| JSON | `.json` | translation-only (checks 1–2) |
| gettext | `.po` | `msgid` → `msgstr` (all checks) |
| XLIFF | `.xliff`, `.xlf` | `<target>` text (checks 1–2) |
| Fluent | `.ftl` | `key = value` (checks 1–2) |

## Install

```bash
pip install i18n-security-lint
```

Or, for development, from this directory:

```bash
pip install -e .
```

## Usage

```bash
# Scan one or more locale files
i18n-security-lint locale/*.po

# Scan a directory recursively, emit JSON, fail CI on any finding
i18n-security-lint --json --strict locale/
```

Exit code is `1` when `--strict` is set and at least one finding is reported,
so the tool drops straight into a CI pipeline.

## GitHub Action

```yaml
- uses: ecogetaway/oss-language-inclusion/tools/i18n-security-lint@main
  with:
    path: locale/
```

## Status

v0.2. All four checks are implemented: bidi and XSS for every
supported format, format-specifier and interpolation-variable drift for `.po`
source/translation pairs. The test suite covers each check across JSON, gettext,
XLIFF, and Fluent corpus files, and the repository's CI dogfoods the scanner
against the malicious corpus on every push (it must flag every malicious file
and pass the clean one). This is the flagship security deliverable of the Open
Source Language Inclusion initiative, demonstrated as required.

**Breaking change in v0.2:** rule ids changed. `BIDI_OVERRIDE` now fires only on
true overrides (`U+202D`/`U+202E`), with `BIDI_UNBALANCED` and
`BIDI_DEPRECATED_EMBEDDING` covering the other cases; `PLACEHOLDER_DRIFT` is
replaced by `FORMAT_SPECIFIER_DRIFT` and `INTERPOLATION_DRIFT`. Update any CI
configuration that filters on rule ids. Migration table in the
[spec](../../spec/translated-string-security-checks.md).

Known limitations: detection is pattern-based, not parser-accurate — see the
repository's [SECURITY.md](../../SECURITY.md) for scope and how to report
bypasses.

## License

Apache-2.0 (inherited from the parent repository).
