Download the PHP package yoeunes/icu-parser without Composer

ICU Parser: Static Analysis, Linter & AST Generator

ICU Parser is a PHP 8.2+ library that treats ICU MessageFormat strings as code.

Unlike simple wrappers around MessageFormatter, ICU Parser implements a compiler-style pipeline (Lexer → Parser → AST) and provides static analysis for ICU messages.

This architecture allows for advanced tooling:

• Parsing: Parse ICU messages into a structured, typed AST.
• Validation: Detect common syntax and semantic errors.
• Type Inference: Extract parameter types from messages.
• Linting: Validate translation catalogs across multiple locales.
• Analysis: Syntax highlighting, pretty-formatting, and debugging.

Built for validation, analysis, and robust tooling in i18n workflows.

If you are new to ICU Parser, start with the docs/overview.md.

Getting started

Requirements: PHP 8.2+ and ext-intl (the MessageFormatter class).

What ICU Parser provides

• 🏗️ Deep Parsing: Parse ICU MessageFormat strings into a structured, typed AST.
• 🔍 Type Inference: Extract parameter types and their expected formats from messages.
• ✅ Validation: Detect syntax errors, missing plural categories, and semantic issues.
• 📊 Catalog Analysis: Analyze translation files for consistency and completeness.
• 🎨 Syntax Highlighting: Colorize ICU messages for better readability.
• 🔧 Visitor API: A flexible API for building custom ICU analysis tools.
• 🛠️ CLI Tooling: Lint, audit, debug, and highlight messages from the command line.

Philosophy & Scope

ICU Parser is a static analysis tool, not a runtime formatter.

What it does

• Parse: Converts ICU MessageFormat strings into an AST.
• Validate: Checks for syntax errors and common semantic issues.
• Analyze: Infers types, formats messages, and highlights syntax.
• Lint: Scans translation files for errors and inconsistencies.

What it does NOT do

• Runtime Formatting: It does not format messages at runtime. Use MessageFormatter from ext-intl for that.
• Complete ICU Coverage: It supports the most common ICU constructs but does not cover every edge case or locale-specific nuance.
• MessageFormat 2 (MF2): It targets ICU MessageFormat 1.x only.

Validation notes

• Well-tested behavior: Parsing, AST structure, error offsets, and syntax validation for the supported ICU syntax.
• Heuristic: Semantic validation is conservative and may miss edge cases. Treat it as a helpful tool, not a complete validator.
• Context matters: Locale-specific rules (e.g., plural categories) vary. Use symfony/intl for better locale support.

How it works

• IcuParser::parse() converts an ICU string into an AST.
• The lexer produces a token stream.
• The parser builds an AST (MessageNode).
• Visitors walk the AST to validate, infer types, highlight, or format.

For the full architecture, see docs/ARCHITECTURE.md.

CLI quick tour

PHP API at a glance

Integrations

ICU Parser integrates with common PHP tooling:

• Symfony bundle: See docs/overview.md
• PHPStan: PHPStan rule (early/experimental)
• Twig: Twig extractor (used by the audit command; requires Twig)
• GitHub Actions: Use bin/icu lint in your CI pipeline

Documentation

Start here:

• Quick Start - Get started in a few minutes
• Overview - Scope and capabilities
• Usage Guide - Detailed API usage
• ICU Support - Supported constructs

Key references:

• Architecture - Internal design
• Formatting - Formatting and highlighting

Contributing

Contributions are welcome! See CONTRIBUTING.md to get started.

License

Released under the MIT License.

Support

If you run into issues or have questions, please open an issue on GitHub: https://github.com/yoeunes/icu-parser/issues.