# Localize recipes

> Write metric units, cooking times, and oven temperatures in another language with a label pack, use it for most of the React parts' text, and make your own.

Source: https://recipe-book.siraj.page/guides/localize-recipes/

To write the formatting functions' labels in another language, pass a label pack from [`@recipe-book/core/labels`](https://recipe-book.siraj.page/reference/core/labels.md) as `labels`, with a `locale` for that language's numbers. The functions write English labels by default. In a React app, import this pack from `@recipe-book/react/core/labels`, and pass the parts the pack for your language from `@recipe-book/react/labels`, as [Localize a React app](https://recipe-book.siraj.page/guides/localize-recipes.md#localize-a-react-app) shows.

```ts
import {
  formatDuration,
  formatQuantity,
  formatTemperature,
} from '@recipe-book/core'
import { de } from '@recipe-book/core/labels'

const german = { locale: 'de-DE', labels: de }

formatQuantity({ amount: 2, unit: 'tbsp' }, german) // '2 EL'
formatQuantity({ amount: 1.5, unit: 'pinch' }, german) // '1 ½ Prisen'
formatDuration(90, german) // '1 Std. 30 Min.'
formatTemperature({ value: 180, unit: 'C' }, { ...german, unitDisplay: 'long' }) // '180 Grad Celsius'
```

There are packs for German (`de`), French (`fr`), Dutch (`nl`), Swedish (`sv`), Danish (`da`), Norwegian (`nb`), Italian (`it`), and Spanish (`es`). `labels` sets only the words, so without a `locale` the numbers stay English, as in 1.5 Prisen with `fractions: false`.

## Format a recipe

These examples use the sample recipe from `examples/node-script`:

recipe.ts
```ts title="recipe.ts"
import type { RecipeInput } from '@recipe-book/core'

export const pancakes = {
  name: 'Buttermilk pancakes',
  servings: 4,
  times: { prep: 10, cook: 15 },
  ingredients: [
    { name: 'all-purpose flour', quantity: '1 ½ cups', equivalents: ['190 g'] },
    { name: 'sugar', quantity: '2 tbsp', equivalents: ['25 g'] },
    { name: 'baking powder', quantity: '2 tsp' },
    { name: 'buttermilk', quantity: '1 ¼ cups' },
    { name: 'egg', plural: 'eggs', quantity: 2 },
    {
      name: 'butter',
      quantity: '3 tbsp',
      note: 'melted',
      equivalents: ['42 g'],
    },
    { name: 'maple syrup', note: 'to serve' },
  ],
  steps: [
    'Whisk the dry ingredients in a large bowl.',
    'Whisk the buttermilk, eggs, and butter, then fold into the dry ingredients.',
    'Cook ¼-cup portions on a buttered griddle, 2–3 minutes per side.',
  ],
} satisfies RecipeInput
```

Pass the same options to every formatting function you call. This resolves the recipe to metric, then writes its ingredients and times in German:

```ts {13,18,23-24}
import {
  formatDuration,
  formatIngredient,
  parseRecipe,
  resolveRecipe,
} from '@recipe-book/core'
import { de } from '@recipe-book/core/labels'
import { pancakes } from './recipe.ts'

const result = parseRecipe(pancakes)
if (!result.success) throw result.error

const german = { locale: 'de-DE', labels: de }
const resolved = resolveRecipe(result.data, { system: 'metric' })

for (const section of resolved.ingredients) {
  for (const item of section.items) {
    console.log(formatIngredient(item, german).text)
  }
}

const { prep, cook } = result.data.times
if (prep !== undefined) console.log(formatDuration(prep, german))
if (cook !== undefined) console.log(formatDuration(cook, german))
```

Output
```txt title="Output"
190 g all-purpose flour
2 EL sugar
2 TL baking powder
296 ml buttermilk
2 eggs
3 EL butter, melted
maple syrup, to serve
10 Min.
15 Min.
```

The units are German, but the ingredient names and the note are the recipe's own, so [translate them](https://recipe-book.siraj.page/guides/localize-recipes.md#what-a-pack-doesnt-translate) in the recipe itself.

A [count unit's size](https://recipe-book.siraj.page/reference/core/formatting.md#formatingredient) takes the pack's words too: its unit, and the pack's `size` words in place of "each" and "total", as in 2 Dosen (425 g pro Stück).

## Spell out units

Pass `unitDisplay: 'long'` for the pack's long labels:

```ts
import { formatDuration, formatQuantity } from '@recipe-book/core'
import { de } from '@recipe-book/core/labels'

const german = { locale: 'de-DE', labels: de, unitDisplay: 'long' } as const

formatQuantity({ amount: 2, unit: 'tbsp' }, german) // '2 Esslöffel'
formatDuration(90, german) // '1 Stunde 30 Minuten'
```

## Plural forms

Each label has a singular (`one`) and a plural (`other`). The pack's `language` picks between them with that language's rules, so 1.5 pinches is plural in German but singular in French:

```ts
import { formatQuantity } from '@recipe-book/core'
import { de, fr } from '@recipe-book/core/labels'

const pinches = { amount: 1.5, unit: 'pinch' } as const

formatQuantity(pinches, { locale: 'de-DE', labels: de, fractions: false }) // '1,5 Prisen'
formatQuantity(pinches, { locale: 'fr-FR', labels: fr, fractions: false }) // '1,5 pincée'
```

The amount as printed picks the form, so 1.04 pinches, which kitchen rounding prints as 1, is 1 Prise, but 1,04 Prisen with `rounding: 'none'`. A fraction below 1 takes the form 1 takes, as in ½ Prise, and a range is plural, as in 1–1,5 pincées, unless its ends round to the same number, which takes that number's form, as in 1 pincée for 1–1.04 pinches. English follows its own rule, so its labels never change between runtimes. Every other language uses the runtime's `Intl` data, so read the caution under [`LabelWords`](https://recipe-book.siraj.page/reference/core/types.md#labelwords) before you render on both a server and a browser.

## Write your own pack

Make a pack with [`labelPack`](https://recipe-book.siraj.page/reference/core/labels.md#labelpack) from `@recipe-book/core/labels`. A pack can leave words out: any unit or duration unit it leaves out keeps its English labels, as does a temperature's long form without `temperature`, and a pack without `size` writes "each" and "total":

```ts
import { formatQuantity } from '@recipe-book/core'
import { labelPack } from '@recipe-book/core/labels'

const spoons = labelPack({
  language: 'de',
  units: {
    tbsp: {
      short: { one: 'Essl.', other: 'Essl.' },
      long: { one: 'Esslöffel', other: 'Esslöffel' },
    },
  },
})

formatQuantity({ amount: 2, unit: 'tbsp' }, { labels: spoons }) // '2 Essl.'
formatQuantity({ amount: 2, unit: 'tsp' }, { labels: spoons }) // '2 tsp'
```

To change one unit in a shipped pack, spread it into a new object and pass that to `labelPack`. The spread copy alone isn't a pack, and TypeScript rejects it as `labels`. The shipped packs are frozen, so you can't change them in place. No shipped pack labels `cup` or `cup-metric`, so a pack that labels one leaves the other in English. Every shipped pack labels `tbsp-au`, the Australian tablespoon, as it labels `tbsp`, but each is its own entry. Change both, or a recipe read with `units: { tbsp: 'tbsp-au' }` keeps the old label:

```ts
import { formatQuantity } from '@recipe-book/core'
import { de, labelPack } from '@recipe-book/core/labels'

const tbsp = {
  short: { one: 'Essl.', other: 'Essl.' },
  long: { one: 'Esslöffel', other: 'Esslöffel' },
}

const myGerman = labelPack({
  ...de,
  units: { ...de.units, tbsp, 'tbsp-au': tbsp },
})

formatQuantity({ amount: 2, unit: 'tbsp' }, { locale: 'de-DE', labels: myGerman }) // '2 Essl.'
formatQuantity({ amount: 2, unit: 'tbsp-au' }, { locale: 'de-DE', labels: myGerman }) // '2 Essl.'
formatQuantity({ amount: 2, unit: 'tsp' }, { locale: 'de-DE', labels: myGerman }) // '2 TL'
```

## Localize a React app

A React app installs only `@recipe-book/react`, so it imports its pack from [`@recipe-book/react/labels`](https://recipe-book.siraj.page/reference/react/labels.md). Each pack there holds the words of core's pack of the same name, plus the text of the parts' controls. It leaves out the terms of [`<Recipe.Times>`](https://recipe-book.siraj.page/reference/react/times.md) and [`<Recipe.Nutrition>`](https://recipe-book.siraj.page/reference/react/nutrition.md) and the text of [`<Recipe.CookMode>`](https://recipe-book.siraj.page/reference/react/cook-mode.md), which stay in English unless you set them. Pass it as `labels` to a [`<Recipe.Provider>`](https://recipe-book.siraj.page/reference/react/provider.md), with a `locale` for the numbers, even from a layout that's a Server Component, as the `@recipe-book/react/labels` reference shows. To format in a Server Component, as in [Format a recipe](https://recipe-book.siraj.page/guides/localize-recipes.md#format-a-recipe), import core's pack of the same name from [`@recipe-book/react/core/labels`](https://recipe-book.siraj.page/reference/react/labels.md#imports-on-cores-pages).

[`<Recipe.Times>`](https://recipe-book.siraj.page/reference/react/times.md) writes its durations in English under every pack, as in "1 hr 30 min". For German times, format each time's `minutes` with [`formatDuration`](https://recipe-book.siraj.page/reference/core/formatting.md#formatduration) and the same pack, in a [`children` function](https://recipe-book.siraj.page/reference/react/times.md#render-your-own-rows):

```tsx {3,13-15}
'use client'

import { formatDuration, type ParsedRecipe } from '@recipe-book/react/core'
import * as Recipe from '@recipe-book/react'
import { de } from '@recipe-book/react/labels'

export function CookingTimes({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.Times>
        {(time) => (
          <div>
            <dt>{time.label}</dt>
            <dd>
              {formatDuration(time.minutes, { locale: 'de-DE', labels: de })}
            </dd>
          </div>
        )}
      </Recipe.Times>
    </Recipe.Root>
  )
}
```

The term "Prep time" comes from `labels.prepTime`, so add it and its siblings to a pack of your own, made as in [Change one word](https://recipe-book.siraj.page/reference/react/labels.md#change-one-word).

## What a pack doesn't translate

A pack holds only the words Recipe Book writes. These stay as they are:

- Ingredient names, notes, and step text are the recipe's own. Translate them in the recipe.
- A pack doesn't change how recipe text reads. An ingredient line reads only a [unit alias](https://recipe-book.siraj.page/reference/core/units.md#unitalias), such as `EL` or `can`, so under `de`, `'1 Dose Tomaten'` has no unit and doubles to "2 Dose Tomatens", while `'1 can Tomaten'` doubles to "2 Dosen Tomaten". A line also reads `'1.500 g'` as 1.5 g. With `decimal: ','`, as in [Read regional recipes](https://recipe-book.siraj.page/guides/author-recipes.md#read-regional-recipes), it keeps the whole line as the name and warns with an [`invalid_quantity`](https://recipe-book.siraj.page/errors/invalid_quantity.md) issue, since 1.500 could be 1500 or 1,5, so write `'1500 g'`.
- A yield's word is the recipe's own too. With `labels`, [`formatYield`](https://recipe-book.siraj.page/reference/core/formatting.md#formatyield) uses the pack's language to pick between `unit` and `plural`, so `{ amount: 1.5, unit: 'pain', plural: 'pains' }` is 1 ½ pain in French. [`<Recipe.YieldText>`](https://recipe-book.siraj.page/reference/react/servings.md#yieldtext) is the exception: it writes a yield in a mass or volume unit in the pack's words for a recipe whose servings have a valid amount. So under `de`, `yield: '4 tbsp'` reads "4 EL" with `servings: 4`, and "4 tbsp" without servings.
- No shipped pack labels the US units, such as `cup` and `oz`, because each language's own word for them names another size, so they keep their English labels. Resolve the recipe to metric, as in [Format a recipe](https://recipe-book.siraj.page/guides/localize-recipes.md#format-a-recipe), to show metric units instead. `handful`, `jar`, `stalk`, and `bag` stay English too, since the shipped packs don't label them. A pack you make with [`labelPack`](https://recipe-book.siraj.page/reference/core/labels.md#labelpack) can.
- No shipped pack labels the 250 mL `cup-metric` either, so it keeps its English label, "cup". It's a metric unit, so resolving to metric keeps it too: under `de`, `{ name: 'Zucker', quantity: { amount: 1, unit: 'cup-metric' } }` reads "1 cup Zucker". Write the quantity in mL instead, or label `cup-metric` in a pack of your own, as in [Write your own pack](https://recipe-book.siraj.page/guides/localize-recipes.md#write-your-own-pack).
- [`formatServings`](https://recipe-book.siraj.page/reference/core/formatting.md#formatservings) writes only numbers, so it ignores `labels`.
- [`toJsonLd`](https://recipe-book.siraj.page/reference/core/schema-org.md#tojsonld) writes its quantities in English, whatever the recipe's language.

## Reference

- [Label packs](https://recipe-book.siraj.page/reference/core/labels.md) lists every pack's labels and the words no pack holds.
- [`LabelWords`](https://recipe-book.siraj.page/reference/core/types.md#labelwords) documents the words a pack holds, how its language picks a plural form, and what [`labelPack`](https://recipe-book.siraj.page/reference/core/labels.md#labelpack) checks.
- [React's label packs](https://recipe-book.siraj.page/reference/react/labels.md) lists the text each React pack adds for the parts' controls.
- [Formatting](https://recipe-book.siraj.page/reference/core/formatting.md) documents the `labels` option on each formatting function.
- [`invalid_argument`](https://recipe-book.siraj.page/errors/invalid_argument.md) explains the errors an invalid pack throws.
