![\"pofile-ts\"](\"logo.svg\")
\n \n\n \n \n \n
\n Parse, compile & transform PO files — 20× faster\n
\n\n[](https://github.com/sebastian-software/pofile-ts/actions/workflows/ci.yml)\n[](https://codecov.io/gh/sebastian-software/pofile-ts)\n[](https://www.npmjs.com/package/pofile-ts)\n[](https://www.npmjs.com/package/pofile-ts)\n[](https://bundlephobia.com/package/pofile-ts)\n[](https://bundlephobia.com/package/pofile-ts)\n[](https://nodejs.org/)\n[](https://bun.sh/)\n\n**pofile-ts** is a modern i18n toolkit for [GNU gettext](https://www.gnu.org/software/gettext/) PO files. Not just a parser — includes an ICU compiler with 3-4× faster runtime than Lingui/FormatJS, native CLDR plural rules, and format conversion helpers. Zero dependencies. TypeScript-first. Built for Node 20+, Bun, and modern browsers.\n\n## Why pofile-ts?\n\n- **20× faster parsing** — Hand-optimized with first-char dispatch and fast-paths. No regex soup.\n- **ICU Compiler** — Compile ICU messages to JavaScript functions. 3-4× faster runtime than Lingui and FormatJS.\n- **Native CLDR plurals** — Uses `Intl.PluralRules` for all 100+ locales. Zero CLDR data in bundle.\n- **CSP-safe** — No `eval()`, no `new Function()`. Works in strict security environments.\n- **Modern-first** — Built for Node 20+, ESM-native, tree-shakeable. No legacy polyfills.\n- **Zero dependencies** — ~11KB full, ~5KB tree-shaken. No transitive deps, no supply chain bloat.\n\n## Features\n\n### Core\n\n- 📖 **Parse** PO files from strings — 20× faster than pofile, 7× faster than gettext-parser\n- ✏️ **Serialize** PO files back to strings — 2.5× faster than pofile, ~4.5× faster than gettext-parser\n- 🎯 **Full PO support** — headers, comments, flags, plurals, message context\n\n### i18n Toolkit\n\n- 🌍 **CLDR plural rules** — Uses native `Intl.PluralRules`, zero bundle size for CLDR data\n- 🔄 **ICU MessageFormat** — Convert between Gettext plurals and ICU syntax\n- 🧩 **ICU Parser** — Parse and analyze ICU messages (<3KB gzipped, 5× faster than FormatJS)\n- ⚡ **ICU Compiler** — Compile ICU messages to fast JavaScript functions (3-4× faster at runtime)\n- 🔢 **Plural helpers** — Get categories, counts, and selector functions for any locale\n- 🆕 **Extended Intl Formatters** — Lists, durations, relative times, and display names built-in\n\n### Format Styles\n\n- 🎨 **50+ built-in styles** — `compact`, `percent`, `bytes`, `iso`, `relative`, and more\n- 🔧 **Custom styles** — Register your own `Intl.NumberFormat`, `DateTimeFormat`, `ListFormat` options\n- 💱 **Dynamic currency** — Currency code read from message values at runtime\n- 🏭 **Factory pattern** — `createIcuCompiler()` for pre-configured, reusable compilers\n\n### Developer Experience\n\n- 📦 **Zero dependencies** — No bloat, no supply chain risk\n- 🌳 **Tree-shakeable** — ~5KB for PO parsing only, ~11KB full\n- 💎 **TypeScript-first** — Written in TypeScript, full type definitions\n- 🛡️ **CSP-safe** — No `eval()`, no `new Function()`\n- ⚡ **Modern-first** — Node 20+, ESM-native, no legacy polyfills\n\n## Use Cases\n\n- **Vite/Webpack plugins** — Parse and compile PO files at build time for zero runtime cost\n- **TMS pipelines** — Crowdin, Lokalise, Phrase — sync and transform translations\n- **CI/CD validation** — Validate plural forms, variables, and syntax in PRs\n- **Custom tooling** — Low-level APIs for message extraction and code generation\n\n## Installation\n\n```bash\nnpm install pofile-ts\n```\n\n## Quick Start\n\n```typescript\nimport { parsePo, stringifyPo } from \"pofile-ts\"\n\nconst po = parsePo(`\nmsgid \"Hello\"\nmsgstr \"Hallo\"\n`)\n\nconsole.log(po.items[0].msgid) // \"Hello\"\nconsole.log(po.items[0].msgstr) // [\"Hallo\"]\n\nconsole.log(stringifyPo(po))\n```\n\n### ICU MessageFormat\n\nA fast, lightweight ICU MessageFormat parser — 5× faster and 4× smaller than FormatJS:\n\n```typescript\nimport { parseIcu, extractVariables, validateIcu, hasPlural } from \"pofile-ts\"\n\n// Parse ICU messages into an AST\nconst result = parseIcu(\"{count, plural, one {# item} other {# items}}\")\nif (result.success) {\n console.log(result.ast) // AST with plural node\n}\n\n// Extract variables from messages\nextractVariables(\"{name} has {count} messages\")\n// → [\"name\", \"count\"]\n\n// Validate syntax before use\nconst validation = validateIcu(\"{gender, select, male {He} other {They}}\")\nconsole.log(validation.valid) // true\n\n// Check message structure\nhasPlural(\"{n, plural, one {#} other {#}}\") // true\nhasPlural(\"Hello {name}\") // false\n```\n\nSupports ICU MessageFormat v1: arguments, plurals, selects, selectordinals, number/date/time formatting, tags, and escaping. Trade-offs for size: no AST location tracking, styles stored as opaque strings.\n\n### ICU Compiler\n\nCompile ICU messages to fast JavaScript functions — about 3× faster than intl-messageformat and 4× faster than Lingui at runtime:\n\n```typescript\nimport { compileIcu, compileCatalog, generateCompiledCode } from \"pofile-ts\"\n\n// Compile a single message\nconst greet = compileIcu(\"Hello {name}!\", { locale: \"en\" })\ngreet({ name: \"World\" }) // → \"Hello World!\"\n\n// Full ICU support: plurals, select, number/date/time, tags\nconst msg = compileIcu(\"{count, plural, one {# item} other {# items}} in cart\", {\n locale: \"en\"\n})\nmsg({ count: 5, link: (text) => `${text}` })\n// → \"5 items in cart\"\n\n// Dynamic currency from values\nconst price = compileIcu(\"{amount, number, currency}\", { locale: \"de\" })\nprice({ amount: 99.99, currency: \"EUR\" }) // → \"99,99 €\"\nprice({ amount: 99.99, currency: \"USD\" }) // → \"99,99 $\"\n\n// Custom format styles with full Intl options\nconst size = compileIcu(\"{bytes, number, filesize}\", {\n locale: \"en\",\n numberStyles: {\n filesize: { style: \"unit\", unit: \"kilobyte\", unitDisplay: \"short\" }\n }\n})\nsize({ bytes: 512 }) // → \"512 kB\"\n\n// Compile an entire catalog at runtime\nconst compiled = compileCatalog(catalog, { locale: \"de\" })\ncompiled.format(\"messageId\", { name: \"Sebastian\" })\n\n// Or generate static code for build-time compilation\nconst code = generateCompiledCode(catalog, { locale: \"de\" })\n// → TypeScript file with pre-compiled functions\n```\n\nSupports named tags (``), numeric tags (`<0>`, `<1>` — Lingui-style), and React components (returns array when tag functions return objects).\n\n### Extended Intl Formatters\n\nGo beyond standard ICU with built-in support for modern `Intl` APIs:\n\n```typescript\nimport { compileIcu } from \"pofile-ts\"\n\n// Lists — \"Alice, Bob, and Charlie\" or \"Alice, Bob, or Charlie\"\nconst list = compileIcu(\"{authors, list}\", { locale: \"en\" })\nlist({ authors: [\"Alice\", \"Bob\", \"Charlie\"] }) // → \"Alice, Bob, and Charlie\"\n\n// Relative time — \"in 3 days\" or \"2 hours ago\"\nconst ago = compileIcu(\"{days, ago, day}\", { locale: \"de\" })\nago({ days: -2 }) // → \"vor 2 Tagen\"\n\n// Display names — Localized country, language, currency names\nconst name = compileIcu(\"{lang, name, language}\", { locale: \"de\" })\nname({ lang: \"en\" }) // → \"Englisch\"\n\n// Durations — \"2 hours, 30 minutes\" (Baseline 2025)\nconst dur = compileIcu(\"{time, duration, short}\", { locale: \"en\" })\ndur({ time: { hours: 2, minutes: 30 } }) // → \"2 hr, 30 min\"\n```\n\nAll formatters use native browser APIs — zero additional bundle size. See [browser support](https://sebastian-software.github.io/pofile-ts/docs/helpers#browser-support).\n\n## Documentation\n\nFor full documentation including API reference, i18n helpers, and migration guide:\n\n**[📖 Documentation](https://sebastian-software.github.io/pofile-ts/)**\n\n## Performance\n\nSpeed matters for build tools and CI pipelines. pofile-ts is hand-optimized for performance — no regex soup, no unnecessary allocations, just fast parsing.\n\n_Benchmarked on Apple M1 Ultra, Node.js 22. Relative performance is consistent across different hardware._\n\n### PO File Parsing\n\n10,000 entries (~10% plurals):\n\n| Library | Parsing | Serialization |\n| -------------- | ------------: | ------------: |\n| **pofile-ts** | **209 ops/s** | **256 ops/s** |\n| gettext-parser | 28 ops/s | 54 ops/s |\n| pofile | 8 ops/s | 100 ops/s |\n\n→ **20× faster parsing** vs pofile, **7× faster** vs gettext-parser\n\n### ICU MessageFormat Parsing\n\nRealistic messages with plurals, selects, nested structures, and tags:\n\n| Library | Speed | Bundle (gzip) |\n| ---------------------------------- | ------------: | ------------: |\n| **pofile-ts** | **5× faster** | **<3KB** |\n| @formatjs/icu-messageformat-parser | baseline | ~9KB |\n\n→ **5× faster**, **4× smaller bundle**\n\n### ICU Compilation & Runtime\n\nCompiling ICU messages to functions and executing them:\n\n| Metric | pofile-ts | vs intl-messageformat | vs @lingui (compiled) |\n| ----------------- | --------: | --------------------: | --------------------: |\n| **Compilation** | 409k op/s | **7× faster** | — |\n| **Runtime** | 792k op/s | **3× faster** | **4× faster** |\n| **Catalog (200)** | ~1.35M/s | **7× faster** | — |\n\n→ **3× faster** at runtime vs intl-messageformat, **4× faster** vs Lingui\n\n## Bundle Size\n\nThe full library is **~11KB gzipped**. Tree-shaking lets you import only what you need:\n\n| Export | Gzipped |\n| -------------- | ------: |\n| PO parsing | ~5KB |\n| Plural helpers | ~1KB |\n| ICU conversion | ~2KB |\n| ICU parser | ~3KB |\n\nPlural helpers use native `Intl.PluralRules` — no CLDR data in the bundle.\n\nAll exports are **named exports** — modern bundlers (Vite, esbuild, Rollup, webpack) automatically tree-shake unused code.\n\n## Monorepo Structure\n\n```\npackages/pofile-ts/ # The library (published to npm)\napps/docs/ # Documentation site (Fumadocs)\nbenchmark/ # Performance benchmarks\n```\n\n## Development\n\n```bash\npnpm install\npnpm test # Run tests\npnpm build # Build library\npnpm docs:dev # Start docs dev server\n```\n\n## Credits\n\nOriginally forked from [pofile](https://github.com/rubenv/pofile) by Ruben Vermeersch. Completely rewritten with modern TypeScript, expanded with CLDR plural support, ICU conversion, and comprehensive i18n helpers.\n\nMaintained by [Sebastian Software](https://sebastian-software.de/).\n\n## License\n\n[MIT](LICENSE) — Use it freely in personal and commercial projects.\n","readmeFilename":"README.md"}