Skip to content
New: Customize your theme with an AI assistant. Read the guide

Internationalization

Files: src/config/language.json, src/config/config.toml, src/i18n/, src/config/menu.<language>.json, src/content/**/<language>/ · Skill level: Beginner

Givo ships in English (the default, at /), French (at /fr/), and Arabic (at /ar/), with the whole layout mirrored on Arabic pages. Every page, menu, label, amount, and date exists in every language. You can keep all three, keep only your default language, or add another one. For how right-to-left works, see RTL & Arabic.

What Makes Up A Language

PartFiles
The language itselfan entry in src/config/language.json
Page and section texta folder per language in every content folder, such as src/content/causes/french/ and src/content/sections/arabic/
Interface textsrc/i18n/<language>.json, such as fr.json: buttons, labels, form messages, campaign labels (“Ended”, “Last day”, “days left”), the page-title tagline
Menussrc/config/menu.<language>.json, such as menu.ar.json
[
{
"languageName": "En",
"languageCode": "en",
"contentDir": "english",
"weight": 1,
"ogLocale": "en_US",
"dir": "ltr",
"dateLocale": "en-US"
},
{
"languageName": "Fr",
"languageCode": "fr",
"contentDir": "french",
"weight": 2,
"ogLocale": "fr_FR",
"dir": "ltr",
"dateLocale": "fr-FR"
},
{
"languageName": "Ar",
"languageCode": "ar",
"contentDir": "arabic",
"weight": 3,
"ogLocale": "ar_SA",
"dir": "rtl",
"dateLocale": "ar"
}
]
KeyWhat it does
languageNameThe label on the language links
languageCodeThe URL prefix and the file suffix (fr.json, menu.fr.json)
contentDirThe folder name inside each content folder
weightThe order of the language links
ogLocaleThe language of social previews
dirltr or rtl. This one value sets the direction of the page
dateLocaleThe format of dates, numbers, and amounts

Visitors switch language with the links in the header, the mobile menu, and the footer. A link goes to the same page in the other language.

Your organization details stay in one place for every language: [organization] in config.toml (name, registration number, phone, address, hours). Don’t type them into translations. See Organization Info.

Language Settings

src/config/config.toml
[settings.multilingual]
enable = true
defaultLanguage = "en"
disableLanguages = [""] # e.g. ["fr"] to switch French off without deleting it
showDefaultLangInUrl = false # true: English at /en/ instead of /

Restart npm run dev after you change these values.

Translate Or Edit Text

  • Page and section text: edit the file with the same name in the language’s folder, for example src/content/sections/french/hero-section.md. Keep the keys and structure the same as in English; translate the values only.
  • Interface text: edit the same key in the language’s file, for example navigation.buttonLabel (“Donate”) in src/i18n/fr.json.
  • Menus: each src/config/menu.<language>.json must keep the same structure as menu.en.json: the same items, in the same order, with the same url. Translate the names. Menu and button URLs are written without the language prefix; the theme adds it.
  • Links inside text: a Markdown link in a translated file needs its language prefix, such as [Questions](/fr/faq/). Without it the link opens the English page.

Keep The Numbers The Same In Every Language

Translate words, never figures. These numbers must be identical in every language folder:

  • the giving data in src/content/donate/<language>/-index.md: currency, amounts, default, minimum, coverFeesPercent, the amounts of impactMap, and the tiers amounts. npm run build prints a [donate] warning when they differ. See Donation Form.
  • the goal, raised, donors, and deadline of each cause in src/content/causes/<language>/
  • the dates, times, capacity, and price of each event in src/content/events/<language>/
  • the spending split on /impact/ and its copies on the homepage and the donate page. See Impact & Transparency.

Page-Title Tagline And Site Description

Every page title ends with a tagline: “Clean water wells - your tagline”. Each language has its own, with the default description for pages that don’t set one:

src/i18n/en.json
"seo": {
"tagline": "Charity & Non-Profit Astro & Tailwind CSS Theme",
"siteDescription": "An Astro and Tailwind CSS theme for charities and non-profits: ..."
}

Both ship with the theme’s own sample text. Replace them in every file in src/i18n/ before you launch. Set "tagline": "" to end titles with the organization name instead. A value in tagline or description under [site] in config.toml replaces them in every language, which suits a site with one language. See Site Identity & Logo.

Counted Labels (Plurals)

Labels with a number, such as “1 donor” and “412 donors” or “1 day left” and “12 days left”, come in forms per language. English and French need two keys, the singular and the plural:

// src/i18n/en.json, under "causes"
"donors": "{count} donors",
"donorOne": "{count} donor",

Arabic needs more forms, so ar.json adds keys with a suffix beside the plural key:

// src/i18n/ar.json, under "causes"
"donors": "{count} متبرّع",
"donors_two": "متبرّعان",
"donors_few": "{count} متبرّعين",
"donors_many": "{count} متبرّعًا",
"donorOne": "متبرّع واحد",

The suffixes are _zero, _two, _few, and _many. The browser’s plural rules pick the right form for the number, and a missing form falls back to the plural key. Developers build these labels with countForms and countLabel in src/lib/plural.ts, never by joining strings. When you add a language with more plural forms, add its extra keys the same way; npm run check-i18n accepts them.

Numbers, Amounts, And Dates

Givo formats every amount, number, and date for the page language, from dateLocale in language.json: $96,080 in English shows as 96 080 $ in French. Arabic pages keep Western digits. You never write a formatted amount in content: write plain numbers (goal: 75000), and the theme formats them.

The currency is one value for every language, currency in src/content/donate/<language>/-index.md (an ISO 4217 code such as "USD", "EUR", or "GBP"). Office hours and event times use timezone in [organization]; an event can set its own timezone.

Check Your Translations

Terminal window
npm run check-i18n

It also runs as part of npm run astro-check, and fails when:

  • a key in src/i18n/en.json is missing from another language file, or the reverse (the extra plural keys are allowed),
  • a key in en.json is no longer read by any code,
  • a menu file differs from menu.en.json in structure (item count, url),
  • a content file in an english/ folder has no copy in another language folder, or the reverse.

It warns about empty strings and strings still equal to the English ones. Words that are the same in every language on purpose are listed in scripts/check-i18n.mjs.

Remove A Language

To turn one language off, add its code to disableLanguages in [settings.multilingual], for example ["fr"]. Its files stay in the project, and you can turn it back on later. Restart npm run dev.

To keep only your default language:

  1. Save a git commit or a copy of the folder, because the next steps delete files.
  2. Set enable = false in [settings.multilingual] of src/config/config.toml.
  3. Run npm run dev (or npm run astro-check) once.
  4. Run npm run remove-multilingual. It deletes the content folders of every language except the default one and rewrites language.json.

The script always keeps menu.en.json and en.json. If your default language is not English, remove the other menu and src/i18n/ files by hand.

Add A Language

Example: German, code de, folder german.

  1. Copy every english/ folder under src/content/ to a german/ folder next to it.

  2. Add German to src/config/language.json, with languageName, languageCode ("de"), contentDir ("german"), weight, ogLocale ("de_DE"), dir ("ltr", or "rtl" for a right-to-left language), and dateLocale ("de-DE").

  3. Copy src/config/menu.en.json to menu.de.json, and src/i18n/en.json to de.json.

  4. Translate the copied content, menu, and strings. Add the language prefix to Markdown links in the copied files, such as [Questions](/de/faq/). If German needs more plural forms than English for a label, add the _zero, _two, _few, or _many keys beside it. Keep every number the same as in English.

  5. Run npm run check-i18n and fix what it lists.

  6. On Netlify, add a /de/* block to netlify.toml, copied from the /fr/* block. If the alphabet needs its own font, add it to src/config/fonts.json, using the Arabic font as your model. Restart the dev server.

Do It With AI

Add [LANGUAGE] (code [CODE], folder [FOLDER]) to my Givo site. Follow "Add or remove a language"
in SKILLS.md: copy every english/ content folder, add the language to src/config/language.json,
copy menu.en.json and src/i18n/en.json, and translate the copies. Add the language prefix to
Markdown links in the new files, add plural keys if the language needs them, and keep every number
(donate file, causes, events) identical. Do not run generate-multilingual-content. Then run
npm run check-i18n and fix what it lists.
Translate my changes to every other language: for every file I changed in src/content/**/english/
today, update the file with the same name in each other language folder (same keys, translated
values, numbers unchanged), and add any new key from src/i18n/en.json to the other files in
src/i18n/. Then run npm run check-i18n.
Type something to search...