API Reference

All exports are named functions — no classes, no default export.

Core Functions

Function	Description
`parsePo(content)`	Parse a PO file string into a `PoFile` object
`stringifyPo(po, options?)`	Serialize a `PoFile` to string
`createPoFile()`	Create a new empty `PoFile`
`createItem(options?)`	Create a new translation item
`stringifyItem(item, options?)`	Serialize a single item to string
`parsePluralForms(header)`	Parse the Plural-Forms header value
`createDefaultHeaders(options)`	Create default PO headers (auto-generates Plural-Forms)

Types

PoItem

Prop

Type

PoFile

Prop

Type

SerializeOptions

Prop

Type

i18n Helpers

createDefaultHeaders

Create default PO headers with sensible defaults. When language is provided, Plural-Forms is automatically generated from CLDR data via Intl.PluralRules.

import { createDefaultHeaders } from "pofile-ts"

// Plural-Forms auto-generated from CLDR
const headers = createDefaultHeaders({
  language: "de",
  generator: "my-tool"
})
// → includes "Plural-Forms: nplurals=2; plural=(n != 1);"

// Custom Plural-Forms
const custom = createDefaultHeaders({
  language: "de",
  pluralForms: "nplurals=2; plural=(n > 1);"
})

// Omit Plural-Forms
const noPluralForms = createDefaultHeaders({
  language: "de",
  pluralForms: false
})

CreateHeadersOptions

Prop

Type

Catalog Conversion

Convert between simple key-value catalogs and PO items.

import { catalogToItems, itemsToCatalog } from "pofile-ts"

const catalog = {
  Hello: { translation: "Hallo" },
  "{count} item": {
    translation: ["{count} Element", "{count} Elemente"],
    pluralSource: "{count} items"
  }
}

const items = catalogToItems(catalog)
const backToCatalog = itemsToCatalog(items)

CatalogEntry

Prop

Type

Reference Utilities

Parse and format source file references.

import { parseReference, formatReference, createReference } from "pofile-ts"

parseReference("src/App.tsx:42")
// → { file: "src/App.tsx", line: 42 }

formatReference({ file: "src/App.tsx", line: 42 })
// → "src/App.tsx:42"

createReference("src/Button.tsx", 10)
// → { file: "src/Button.tsx", line: 10 }

SourceReference

Prop

Type

Message ID Generation

Generate stable, collision-resistant IDs from message content.

import { generateMessageId, generateMessageIdSync } from "pofile-ts"

// Async (works in browsers and Node.js)
const id = await generateMessageId("Hello {name}", "greeting")
// → "Kj9xMnPq" (8-char Base64URL)

// Sync (Node.js only, faster)
const syncId = generateMessageIdSync("Hello {name}")

Uses SHA-256 with Base64URL encoding — 281 trillion possibilities, practically zero collisions even at 1M messages.

Plural Categories

Get CLDR plural categories for any locale. Uses the browser's native Intl.PluralRules API — zero bundle size for CLDR data, always up-to-date, CSP-safe.

import { getPluralCategories, getPluralCount, getPluralFunction } from "pofile-ts"

// CLDR-compliant categories via Intl.PluralRules
getPluralCategories("de") // → ["one", "other"]
getPluralCategories("ru") // → ["one", "few", "many", "other"]
getPluralCategories("pl") // → ["one", "few", "many", "other"]
getPluralCategories("ar") // → ["zero", "one", "two", "few", "many", "other"]

getPluralCount("ar") // → 6

// Plural selector function (uses Intl.PluralRules internally)
const fn = getPluralFunction("ru")
fn(1) // → 0 (one)
fn(2) // → 1 (few)
fn(5) // → 2 (many)
fn(21) // → 0 (one) — CLDR-correct!

// Locale normalization (underscore and hyphen both work)
getPluralCategories("pt_BR") // → ["one", "many", "other"]
getPluralCategories("pt-BR") // → ["one", "many", "other"]

How It Works

pofile-ts delegates all plural logic to Intl.PluralRules:

getPluralCategories(locale) → new Intl.PluralRules(locale).resolvedOptions().pluralCategories
getPluralFunction(locale) → Returns index based on pluralRules.select(n)
createDefaultHeaders({ language }) → Auto-generates Plural-Forms header from getPluralCount()

This means:

No CLDR data in the bundle — the browser provides it
Always matches the browser's CLDR version
Works in all modern browsers and Node.js 14+

ICU Conversion

Convert Gettext plurals to ICU MessageFormat.

import { gettextToIcu, normalizeToIcu, icuToGettextSource } from "pofile-ts"

// Single item
gettextToIcu(item, { locale: "de" })
// → "{count, plural, one {Ein Artikel} other {{count} Artikel}}"

// Entire PO file
const normalized = normalizeToIcu(po, { locale: "de" })

// Extract from ICU back to Gettext source
icuToGettextSource("{count, plural, one {# item} other {# items}}")
// → { msgid: "{count} item", msgid_plural: "{count} items", pluralVariable: "count" }

GettextToIcuOptions

Prop

Type

IcuToGettextOptions

Prop

Type

Comment Utilities

Split multiline comments for PO format output.

import { splitMultilineComments } from "pofile-ts"

// Source comments often contain newlines
splitMultilineComments(["Line1\nLine2", "Line3"])
// → ["Line1", "Line2", "Line3"]

// Handles Windows/Mac line endings, trims whitespace
splitMultilineComments(["  First\r\n  Second  "])
// → ["First", "Second"]

API Reference

On this page