i18n Workflow Helpers

import { splitMultilineComments } from "pofile-ts"

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

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

// Trims whitespace, filters empty lines
splitMultilineComments(["  Line1\n\n  Line2  "])
// → ["Line1", "Line2"]

import { createDefaultHeaders } from "pofile-ts"

const headers = createDefaultHeaders({
  language: "de",
  generator: "my-tool"
})

// Includes: POT-Creation-Date, MIME-Version, Content-Type, etc.
// Plural-Forms is auto-generated from CLDR when language is set:
// → "Plural-Forms: nplurals=2; plural=(n != 1);"

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

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

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

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

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

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}")

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"

// Validates relative paths, normalizes Windows backslashes
createReference("src\\components\\Button.tsx", 10)
// → { file: "src/components/Button.tsx", line: 10 }

import { getPluralFormsHeader } from "pofile-ts"

getPluralFormsHeader("de") // → "nplurals=2; plural=(n != 1);"
getPluralFormsHeader("pl") // → "nplurals=4; plural=(n != 1);"
getPluralFormsHeader("ar") // → "nplurals=6; plural=(n != 1);"
getPluralFormsHeader("zh") // → "nplurals=1; plural=0;"

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

// Get categories for a locale
getPluralCategories("de") // → ["one", "other"]
getPluralCategories("ru") // → ["one", "few", "many", "other"]
getPluralCategories("pl") // → ["one", "few", "many", "other"]
getPluralCategories("ar") // → ["zero", "one", "two", "few", "many", "other"]

// Count of plural forms
getPluralCount("de") // → 2
getPluralCount("ru") // → 4
getPluralCount("ar") // → 6

// Get plural selector function
const selectPlural = getPluralFunction("ru")
selectPlural(1) // → 0 (one)
selectPlural(2) // → 1 (few)
selectPlural(5) // → 2 (many)
selectPlural(21) // → 0 (one) — CLDR-correct!
selectPlural(22) // → 1 (few)

getPluralCategories("pt_BR") // → ["one", "many", "other"]
getPluralCategories("pt-BR") // → ["one", "many", "other"]

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

// Convert a single plural item
const item = {
  msgid: "One item",
  msgid_plural: "{count} items",
  msgstr: ["Ein Artikel", "{count} Artikel"]
}

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

// Convert an entire PO file
const po = parsePo(content)
const normalized = normalizeToIcu(po, { locale: "de" })

// All plural items now have ICU in msgstr[0]
normalized.items[0].msgstr[0]
// → "{count, plural, one {Ein Artikel} other {{count} Artikel}}"

// With # in source (e.g. from Lingui)
const item = { msgstr: ["# Artikel", "# Artikel"], ... }

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

// To preserve #, set expandOctothorpe: false
gettextToIcu(item, { locale: "de", expandOctothorpe: false })
// → "{count, plural, one {# Artikel} other {# Artikel}}"

icuToGettextSource("{count, plural, one {# item} other {# items}}")
// → { msgid: "{count} item", msgid_plural: "{count} items", pluralVariable: "count" }

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

const originalIcu = "{count, plural, one {# item} other {# items}}"

// ICU → Gettext (for TMS export)
const gettext = icuToGettextSource(originalIcu, { expandOctothorpe: false })
// → { msgid: "# item", msgid_plural: "# items", pluralVariable: "count" }

// Gettext → ICU (for catalog import)
const backToIcu = gettextToIcu(
  { msgid: gettext.msgid, msgid_plural: gettext.msgid_plural, msgstr: ["# Artikel", "# Artikel"] },
  { locale: "de", pluralVariable: gettext.pluralVariable, expandOctothorpe: false }
)
// → "{count, plural, one {# Artikel} other {# Artikel}}"

// Russian (4 forms) — CLDR-correct "many" for 0, 5-19, 100...
gettextToIcu(ruItem, { locale: "ru" })
// → "{count, plural, one {файл} few {файла} many {файлов} other {файла}}"

// Polish (4 forms)
gettextToIcu(plItem, { locale: "pl" })
// → "{count, plural, one {plik} few {pliki} many {plików} other {pliki}}"

// Arabic (6 forms)
gettextToIcu(arItem, { locale: "ar" })
// → "{count, plural, zero {...} one {...} two {...} few {...} many {...} other {...}}"

import { parseIcu, validateIcu, extractVariables } from "pofile-ts"

// Parse ICU message to AST
const result = parseIcu("{count, plural, one {# item} other {# items}}")
if (result.success) {
  console.log(result.ast) // Array of AST nodes
}

// Validate syntax
const validation = validateIcu("{broken, plural, one {x}}")
console.log(validation.valid) // false
console.log(validation.errors) // [{ kind: "SYNTAX_ERROR", message: "..." }]

// Extract variable names
extractVariables("{name} has {count} messages")
// → ["name", "count"]

// Simple arguments
parseIcu("{name}")

// Formatted arguments
parseIcu("{n, number}")
parseIcu("{d, date, short}")
parseIcu("{t, time, medium}")

// Number/date skeletons (stored as opaque strings)
parseIcu("{n, number, ::currency/EUR}")

// Plural
parseIcu("{n, plural, offset:1 =0 {none} one {# item} other {# items}}")

// Select
parseIcu("{gender, select, male {He} female {She} other {They}}")

// Selectordinal
parseIcu("{n, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}")

// Tags (for rich text / JSX)
parseIcu("Click <link>here</link> to continue")

// Escaping: '' → ' and '{text}' → literal text
parseIcu("It''s {name}''s turn") // "It's {name}'s turn"

// List formatting (Intl.ListFormat)
parseIcu("{items, list}") // conjunction: "Alice, Bob, and Charlie"
parseIcu("{options, list, disjunction}") // "red, blue, or green"
parseIcu("{parts, list, unit}") // "1, 2, 3"

// Duration formatting (Intl.DurationFormat)
parseIcu("{elapsed, duration}") // "2 hours, 30 minutes"
parseIcu("{time, duration, short}") // "2 hr, 30 min"
parseIcu("{playback, duration, digital}") // "2:30:00"

// Relative time formatting (Intl.RelativeTimeFormat)
parseIcu("{days, ago, day}") // "in 3 days" or "3 days ago"
parseIcu("{hours, ago, hour short}") // "in 2 hr."

// Display names (Intl.DisplayNames)
parseIcu("{lang, name, language}") // "en" → "English"
parseIcu("{country, name, region}") // "DE" → "Germany"
parseIcu("{code, name, currency}") // "EUR" → "Euro"

import { compileIcu } from "pofile-ts"

const listFn = compileIcu("{authors, list}", { locale: "en" })
listFn({ authors: ["Alice", "Bob", "Charlie"] })
// → "Alice, Bob, and Charlie"

const agoFn = compileIcu("{days, ago, day}", { locale: "de" })
agoFn({ days: -2 })
// → "vor 2 Tagen"

const nameFn = compileIcu("{lang, name, language}", { locale: "de" })
nameFn({ lang: "en" })
// → "Englisch"

parseIcu("{n, plural, one {#} other {#}}") // ✅ lowercase
parseIcu("{n, PLURAL, one {#} other {#}}") // ✅ uppercase
parseIcu("{n, selectOrdinal, one {#st} other {#th}}") // ✅ camelCase
parseIcu("{n, SelectOrdinal, one {#st} other {#th}}") // ✅ PascalCase
parseIcu("{d, DATE, short}") // ✅ also works

import { extractVariableInfo, compareVariables } from "pofile-ts"

// Get variable details including type and style
extractVariableInfo("{count, number, currency} on {date, date, short}")
// → [
//   { name: "count", type: "number", style: "currency" },
//   { name: "date", type: "date", style: "short" }
// ]

// Compare source and translation variables
compareVariables(
  "Hello {name}, you have {count} messages",
  "Hallo {userName}, du hast {count} Nachrichten"
)
// → { missing: ["name"], extra: ["userName"], isMatch: false }

import { hasPlural, hasSelect, hasSelectOrdinal, hasIcuSyntax } from "pofile-ts"

hasPlural("{n, plural, one {#} other {#}}") // true
hasPlural("{n, selectordinal, one {#st} other {#th}}") // true (ordinal is also plural)

hasSelect("{g, select, male {He} other {They}}") // true

hasSelectOrdinal("{n, selectordinal, one {#st} other {#th}}") // true
hasSelectOrdinal("{n, plural, one {#} other {#}}") // false (cardinal, not ordinal)

hasIcuSyntax("{name}") // true (has argument)
hasIcuSyntax("Hello world") // false (plain text)

import type { IcuNodeType } from "pofile-ts"

// Node types are string literals for easy debugging:
type IcuNodeType =
  | "literal" // Plain text
  | "argument" // {name}
  | "number" // {n, number}
  | "date" // {d, date}
  | "time" // {t, time}
  | "select" // {g, select, ...}
  | "plural" // {n, plural, ...} or {n, selectordinal, ...}
  | "pound" // # in plural
  | "tag" // <b>...</b>

// Type checking is straightforward:
if (node.type === "plural") {
  console.log(node.pluralType) // "cardinal" | "ordinal"
}

parseIcu(message, {
  // Treat tags as literal text (default: false)
  ignoreTag: true,

  // Allow plural/select without 'other' clause (default: true = required)
  requiresOtherClause: false
})

import { compileIcu } from "pofile-ts"

// Compile a single ICU message to a function
const greet = compileIcu("Hello {name}!", { locale: "en" })
greet({ name: "World" }) // → "Hello World!"

// Full ICU support
const msg = compileIcu("{count, plural, one {# item} other {# items}}", { locale: "en" })
msg({ count: 1 }) // → "1 item"
msg({ count: 5 }) // → "5 items"

// Number and date formatting via Intl
const price = compileIcu("{amount, number, ::currency/EUR}", { locale: "de" })
price({ amount: 1234.5 }) // → "1.234,50 €" (German formatting)

// Built-in styles — no configuration needed
compileIcu("{n, number, compact}", { locale: "en" })({ n: 2500000 }) // → "2.5M"
compileIcu("{size, number, megabyte}", { locale: "en" })({ size: 1.5 }) // → "1.5 MB"
compileIcu("{d, date, weekday}", { locale: "en" })({ d: new Date() }) // → "Monday"

// Dynamic currency
compileIcu("{price, number, currency}", { locale: "en" })({ price: 99.99, currency: "EUR" })
// → "€99.99"

// Custom styles with Intl options
compileIcu("{n, number, precise}", {
  locale: "en",
  numberStyles: { precise: { minimumFractionDigits: 2, maximumFractionDigits: 2 } }
})({ n: 3.1 })
// → "3.10"

// Pre-configured compiler for reuse
const compile = createIcuCompiler({
  locale: "de",
  numberStyles: { bytes: { style: "unit", unit: "byte", unitDisplay: "narrow" } }
})
compile("{size, number, bytes}")({ size: 1024 }) // → "1.024B"

// Named tags
const msg = compileIcu("Click <link>here</link> to continue", { locale: "en" })
msg({ link: (text) => `<a href="#">${text}</a>` })
// → "Click <a href="#">here</a> to continue"

// Numeric tags (Lingui-style)
const msg2 = compileIcu("Hello <0>World</0>!", { locale: "en" })
msg2({ 0: (text) => `**${text}**` })
// → "Hello **World**!"

// React components (returns array when tag returns object)
const msg3 = compileIcu("Read our <link>terms</link>", { locale: "en" })
const result = msg3({
  link: (children) => ({ type: Link, props: { to: "/terms" }, children })
})
// → ["Read our ", { type: Link, ... }, ""]
// Use with React.createElement or JSX

import { compileCatalog, itemsToCatalog, parsePo } from "pofile-ts"

const po = parsePo(poFileContent)
const catalog = itemsToCatalog(po.items)

const compiled = compileCatalog(catalog, { locale: "de" })

// Look up by messageId (8-char hash) or msgid
compiled.format("Xk9mLp2Q", { name: "Sebastian" })
compiled.has("Xk9mLp2Q") // true
compiled.keys() // ["Xk9mLp2Q", ...]
compiled.size // 42

compileCatalog(catalog, {
  locale: "de", // Required: for plural rules and Intl formatting
  useMessageId: true, // Use 8-char hash as key (default: true)
  strict: false // Throw on parse errors (default: false)
})

import { generateCompiledCode, parsePo, itemsToCatalog } from "pofile-ts"

const po = parsePo(poFileContent)
const catalog = itemsToCatalog(po.items)

const code = generateCompiledCode(catalog, {
  locale: "de",
  exportName: "messages"
})

// Write to file
fs.writeFileSync("compiled-de.ts", code)

/**
 * Compiled messages for locale: de
 * Generated by pofile-ts
 */

const _pf = (n) => (n !== 1 ? 1 : 0)
const _nf = new Intl.NumberFormat("de")

export const messages = {
  Xk9mLp2Q: (v) => `Hallo ${v?.name ?? "{name}"}!`,
  Ym3nPq4R: (v) =>
    _pf(v?.count ?? 0) === 0
      ? `${_nf.format(v?.count ?? 0)} Artikel`
      : `${_nf.format(v?.count ?? 0)} Artikel`
}

generateCompiledCode(catalog, {
  locale: "de", // Required
  useMessageId: true, // Use 8-char hash as key (default: true)
  exportName: "messages", // Export variable name (default: "messages")
  strict: false // Throw on parse errors (default: false)
})

// ICU plural in msgstr
const catalog1 = {
  Hello: { translation: "{count, plural, one {# Nachricht} other {# Nachrichten}}" }
}

// Gettext plural array (msgstr[0], msgstr[1], ...)
const catalog2 = {
  "{count} message": {
    translation: ["{count} Nachricht", "{count} Nachrichten"],
    pluralSource: "{count} messages"
  }
}

// Both compile to the same runtime behavior
const compiled1 = compileCatalog(catalog1, { locale: "de" })
const compiled2 = compileCatalog(catalog2, { locale: "de" })