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.
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.
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:
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 RecipeInputPass the same options to every formatting function you call. This resolves the recipe to metric, then writes its ingredients and times in German:
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))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:
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:
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”:
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:
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:
'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
ELorcan, so underde,'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. Withdecimal: ',', as in Read regional recipes, it keeps the whole line as the name and warns with aninvalid_quantityissue, 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,formatYielduses the pack’s language to pick betweenunitandplural, 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 underde,yield: '4 tbsp'reads “4 EL” withservings: 4, and “4 tbsp” without servings. - No shipped pack labels the US units, such as
cupandoz, 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, andbagstay English too, since the shipped packs don’t label them. A pack you make withlabelPackcan. - No shipped pack labels the 250 mL
cup-metriceither, so it keeps its English label, “cup”. It’s a metric unit, so resolving to metric keeps it too: underde,{ name: 'Zucker', quantity: { amount: 1, unit: 'cup-metric' } }reads “1 cup Zucker”. Write the quantity in mL instead, or labelcup-metricin a pack of your own, as in Write your own pack. formatServingswrites only numbers, so it ignoreslabels.toJsonLdwrites its quantities in English, whatever the recipe’s language.
Reference
- Label packs lists every pack’s labels and the words no pack holds.
LabelWordsdocuments the words a pack holds, how its language picks a plural form, and whatlabelPackchecks.- React’s label packs lists the text each React pack adds for the parts’ controls.
- Formatting documents the
labelsoption on each formatting function. invalid_argumentexplains the errors an invalid pack throws.