Metadata-Version: 2.4
Name: i18n-security-lint
Version: 0.2.0
Summary: Scans locale files for translated-string security defects (bidi, XSS, format, interpolation).
License: Apache-2.0
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 -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 check families are implemented and covered by tests. The
placeholder checks (3 and 4) need a paired source string, so they run on `.po`
only; JSON, XLIFF, and Fluent are scanned for bidi and XSS. XSS detection is a
substring match rather than a parser, and XLIFF markup is stripped during
extraction — both limitations are recorded in the spec.

**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.

## License

Apache-2.0 (inherited from the parent repository).
