Recipe Book0.6.0

2.11Guides

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.

§ 2.116 min readView as Markdown

To write the formatting functions’ labels in another language, pass a label pack from @recipe-book/core/labels 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 shows.

TypeScript
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
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:

TypeScript
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
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 in the recipe itself.

A count unit’s size 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:

TypeScript
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:

TypeScript
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 before you render on both a server and a browser.

Write your own pack

Make a pack with 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”:

TypeScript
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:

TypeScript
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. 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> and <Recipe.Nutrition> and the text of <Recipe.CookMode>, which stay in English unless you set them. Pass it as labels to a <Recipe.Provider>, 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, import core’s pack of the same name from @recipe-book/react/core/labels.

<Recipe.Times> writes its durations in English under every pack, as in “1 hr 30 min”. For German times, format each time’s minutes with formatDuration and the same pack, in a children function:

TSX
'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.

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, 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, it keeps the whole line as the name and warns with an invalid_quantity 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 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> 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, 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 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.
  • formatServings writes only numbers, so it ignores labels.
  • toJsonLd writes its quantities in English, whatever the recipe’s language.

Reference

  • Label packs lists every pack’s labels and the words no pack holds.
  • LabelWords documents the words a pack holds, how its language picks a plural form, and what labelPack checks.
  • React’s label packs lists the text each React pack adds for the parts’ controls.
  • Formatting documents the labels option on each formatting function.
  • invalid_argument explains the errors an invalid pack throws.
Contents