Migrate to gettext 😌 (#87)

Author: egeakman

.gitignore

@@ -29,3 +29,6 @@ scripts/chapters.yml
 src/data/speakers.json
 src/data/sessions.json
 src/data/schedule.json
+
+# Generated translations
+src/i18n/translations.json

docs/maintaining-translations.md

@@ -0,0 +1,52 @@
+# Maintaining Translations
+
+Feel free to skip the Updating Translations section, but fuzzy translations are important, so take a look 🤗
+
+## Updating Translations
+
+When English text changes in the code, run the update script to synchronize all languages:
+
+```bash
+pnpm run i18n
+```
+
+This script:
+1. Extracts all current `t()` calls from the codebase
+2. Updates the template file (`locales/template/messages.pot`)
+3. Merges changes into all language PO files
+4. Shows statistics about translated, fuzzy, and untranslated strings
+
+**What happens during merge:**
+- **New strings**: Added with empty `msgstr ""` (need translation)
+- **Modified strings**: Marked as "fuzzy" (need review)
+- **Unchanged strings**: Kept as-is
+- **Deleted strings**: Moved to obsolete section at end of file
+
+## Understanding Fuzzy Translations
+
+When the English source text changes slightly, gettext marks translations as "fuzzy":
+
+```po
+#, fuzzy
+msgid "Welcome to our conference"
+msgstr "Konferansımıza Hoş Geldiniz"
+```
+
+The `#, fuzzy` flag means:
+- The English text changed slightly since this was translated
+- The existing translation might still be correct, but needs review
+- Review the translation and remove the `#, fuzzy` line once verified
+
+## Checking Translation Status
+
+The update script shows you:
+- **Translated**: Strings with translations
+- **Fuzzy**: Translations that need review (source text changed)
+- **Untranslated**: Strings without translations (will fall back to English)
+
+Example output:
+
+```
+Merging es...
+  147 translated messages, 8 fuzzy translations, 55 untranslated messages.
+```

docs/translating.md

@@ -0,0 +1,130 @@
+# Translation Guide
+
+This project uses GNU gettext for internationalization. This guide explains how to add new translations and work with the translation system.
+
+## Overview
+
+The translation system follows these principles:
+
+- **English is the source language**: All text in the code is in English, using `t("English text")` calls
+- **Single source of truth**: Language configuration is centralized in `src/i18n/locales.ts`
+- **Standard format**: Uses PO files for translations
+- **Build-time conversion**: PO files are converted to JSON during the build process
+
+## How It Works
+
+### 1. Code Usage
+
+In the `.astro` or `.ts` files, use the `t()` function to mark translatable strings:
+
+```typescript
+const t = useTranslations(lang);
+
+const title = t("Welcome to PyLadiesCon");
+const description = t("Join us for an amazing conference");
+```
+
+For English (the default language), `t()` returns the exact string you pass in. For other languages, it looks up the translation in the PO file.
+
+### 2. Translation Workflow
+
+The system automatically:
+1. Extracts all `t("...")` calls from the codebase
+2. Generates a template file (`messages.pot`) with all strings
+3. Merges new/changed strings into existing language files (`messages.po`)
+4. Converts PO files to JSON at build time for runtime usage
+
+### 3. PO File Format
+
+PO files are plain text files with this structure:
+
+```po
+#: src/components/hero.astro:15
+msgid "Welcome to PyLadiesCon"
+msgstr "PyLadiesCon'a Hoş Geldiniz"
+
+#: src/pages/[lang]/speakers.astro:42
+msgid "Our Speakers"
+msgstr "Konuşmacılarımız"
+```
+
+- `msgid`: The English source text (what you wrote in the code)
+- `msgstr`: The translated text (what users will see)
+- `#:` comments show where the string is used in the codebase
+
+## Adding a New Language
+
+### Step 1: Add to Configuration
+
+Edit `src/i18n/locales.ts` and add your language:
+
+```typescript
+export const languages = {
+  en: "English",
+  es: "Español",
+  tr: "Türkçe",
+  fr: "Français",  // ⬅️ Add your language here
+};
+```
+
+### Step 2: Create the Translation File
+
+Run the bootstrap script with your language code:
+
+```bash
+pnpm run i18n:new fr
+```
+
+This creates `locales/fr/messages.po` with all current strings ready to translate.
+
+### Step 3: Translate the Strings
+
+You have two options for translating:
+
+#### Option A: Using Poedit (Recommended)
+
+[Poedit](https://poedit.net/) is a free and open-source editor for PO files:
+
+1. Download and install [Poedit](https://poedit.net/)
+2. Open `locales/fr/messages.po` in Poedit
+3. Translate each string in the visual interface
+4. Save the file (Poedit handles the format automatically)
+
+#### Option B: Manual Editing
+
+Open `locales/fr/messages.po` in any text editor and fill in the `msgstr` fields:
+
+```po
+msgid "Welcome"
+msgstr "Bienvenue"  # ← Add your translation here
+```
+
+### Step 4: Build and Test
+
+Run the development server to see your translations:
+
+```bash
+pnpm run dev
+```
+
+Visit `http://localhost:4321/fr` or switch the language to see your translations in action.
+
+### Step 5: Submit Your Translations
+
+Once you have completed your translations, submit a pull request to the [main repository](https://github.com/pyladies/global-conference-2025). Aaaand that's it! Your translations will be reviewed and merged for everyone to enjoy. 🎉🎉🎉
+
+## Translation Tips
+
+### Do's
+
+✅ Keep the same formatting (HTML tags, placeholders) as the source text
+✅ Make sure to escape special characters (e.g., quotes, newlines, etc.)
+✅ Try to use gender-neutral language where possible
+✅ Test your translations in the browser to verify context
+
+### Don'ts
+
+❌ Don't change HTML tags or remove them (keep `<strong>`, `<a>`, etc.)
+❌ Don't manually edit `messages.pot` (it's auto-generated)
+
+*See [Maintaining Translations](maintaining-translations.md) for keeping translations working.*