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
| Part | Files |
|---|---|
| The language itself | an entry in src/config/language.json |
| Page and section text | a folder per language in every content folder, such as src/content/causes/french/ and src/content/sections/arabic/ |
| Interface text | src/i18n/<language>.json, such as fr.json: buttons, labels, form messages, campaign labels (“Ended”, “Last day”, “days left”), the page-title tagline |
| Menus | src/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" }]| Key | What it does |
|---|---|
languageName | The label on the language links |
languageCode | The URL prefix and the file suffix (fr.json, menu.fr.json) |
contentDir | The folder name inside each content folder |
weight | The order of the language links |
ogLocale | The language of social previews |
dir | ltr or rtl. This one value sets the direction of the page |
dateLocale | The 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
[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”) insrc/i18n/fr.json. - Menus: each
src/config/menu.<language>.jsonmust keep the same structure asmenu.en.json: the same items, in the same order, with the sameurl. 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 ofimpactMap, and thetiersamounts.npm run buildprints a[donate]warning when they differ. See Donation Form. - the
goal,raised,donors, anddeadlineof each cause insrc/content/causes/<language>/ - the dates, times,
capacity, andpriceof each event insrc/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:
"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
npm run check-i18nIt also runs as part of npm run astro-check, and fails when:
- a key in
src/i18n/en.jsonis missing from another language file, or the reverse (the extra plural keys are allowed), - a key in
en.jsonis no longer read by any code, - a menu file differs from
menu.en.jsonin 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:
- Save a git commit or a copy of the folder, because the next steps delete files.
- Set
enable = falsein[settings.multilingual]ofsrc/config/config.toml. - Run
npm run dev(ornpm run astro-check) once. - Run
npm run remove-multilingual. It deletes the content folders of every language except the default one and rewriteslanguage.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.
-
Copy every
english/folder undersrc/content/to agerman/folder next to it. -
Add German to
src/config/language.json, withlanguageName,languageCode("de"),contentDir("german"),weight,ogLocale("de_DE"),dir("ltr", or"rtl"for a right-to-left language), anddateLocale("de-DE"). -
Copy
src/config/menu.en.jsontomenu.de.json, andsrc/i18n/en.jsontode.json. -
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_manykeys beside it. Keep every number the same as in English. -
Run
npm run check-i18nand fix what it lists. -
On Netlify, add a
/de/*block tonetlify.toml, copied from the/fr/*block. If the alphabet needs its own font, add it tosrc/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 toMarkdown 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 runnpm 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, translatedvalues, numbers unchanged), and add any new key from src/i18n/en.json to the other files insrc/i18n/. Then run npm run check-i18n.