Skip to main content

Custom Formatter

If your project requires some special format or handling logic, you can write your own format implementation.

Formatter is a simple object with 2 main functions parse and serialize, which should take Lingui catalog and serialize it to string and vice versa.

You don't need to create a separate package for formatter, you can write it directly in lingui.config.{ts,js}.

import { extractor } from './my-custom-extractor.ts'
module.exports = {
format: {
catalogExtension: "json",
parse: (content: string): CatalogType => JSON.parse(content),
serialize: (catalog: CatalogType): string => JSON.stringify(catalog),

The shape of formatter is the following:

export type CatalogFormatter = {
catalogExtension: string
* Set extension used when extract to template
* Omit if the extension is the same as catalogExtension
templateExtension?: string
content: string,
ctx: { locale: string | null; sourceLocale: string, filename: string }
): Promise<CatalogType> | CatalogType
catalog: CatalogType,
ctx: { locale: string | null; sourceLocale: string, filename: string; existing: string | null }
): Promise<string> | string

Lingui Catalog is an object with the following structure:

export type CatalogType = {
[msgId: string]: MessageType

type CatalogExtra = Record<string, unknown>

export type MessageType<Extra = CatalogExtra> = {
message?: string
origin?: MessageOrigin[]
comments?: string[]
obsolete?: boolean
context?: string
translation?: string

* the generic field where
* formatters can store additional data
extra?: Extra

If you are using TypeScript to build your formatter, you should use the ts extension for your Lingui configuration file.