KoboToolbox Translation & Localization

Why diff-based? LLMs are non-deterministic, so re-translating an entire document produces slightly different results each time, creating "translation noise" in git diffs. By translating only actual changes, we preserve manual reviewer improvements and reduce unnecessary churn.

🚨 CRITICAL: Pre-Translation Checklist

BEFORE starting translation, read these reference files:

1. brand-terminology.md - For server names, Question Library, Formbuilder, and ALL brand terms
2. ui-terminology.md - For button names, tabs, and capitalization rules

Common mistakes to avoid:

• ❌ Translating server names incorrectly (missing articles or adding extra words)
• ❌ Not including English term on first reference for Formbuilder
• ❌ Missing capital article for "Question Library" / "La bibliothèque de questions" / "La biblioteca de preguntas"
• ❌ Not capitalizing UI terms like "Brouillon" / "Borrador"
• ❌ Using "de" article when it shouldn't be there in French data management terms

Quick Reference

Translation types:

• OFFICIAL - Must use EXACT translation character-for-character (brand terms, UI elements, XLSForm terms)
• Preferred - Can adapt for context (general terminology, course content)

Key principles:

• ALWAYS check brand-terminology.md FIRST before translating any brand-related terms
• Prioritize localization over literal translation
• Use gender-inclusive language
• Maintain consistency with KoboToolbox UI
• Apply appropriate formality level (vous/tu, usted/tú)

Common Translation Pitfalls

⚠️ Brand Terms - Most Frequent Errors

⚠️ First Reference Rule - Frequently Missed

Formbuilder MUST include English on first reference:

⚠️ UI Capitalization - Often Forgotten

⚠️ French Article Usage

Translation Workflow

Step 0: MANDATORY First Step

🔴 STOP! Before translating anything:

1. Identify all brand terms in the source text (KoboToolbox, servers, Question Library, Formbuilder, etc.)
2. Open brand-terminology.md and verify EXACT translations
3. Check ui-terminology.md for any UI elements (buttons, tabs, page names)
4. Note any terms requiring "English + translation" on first reference

Step 1: Identify Content Type

Formal communications (server announcements, formal emails):

• French: Use "vous", addressee "Cher utilisateur, Chère utilisatrice"
• Spanish: Use "usted", addressee "Estimado usuario/a"

User Interface:

• French: Use formal "vous" and "votre"
• Spanish: Use informal "tú"

Courses and educational content (INCLUDES SUPPORT ARTICLES):

• French: Use formal "vous" (even for individuals)
• Spanish: Use informal "tú", "ustedes" for plural
• Examples:
  • FR: "Les utilisatrices et utilisateurs débutant(e)s"
  • ES: "Se te dirigirá" (neutral, not "serás dirigido/a")

Support articles:

• French: Use formal "vous"
• Spanish: Use informal "tú"
• Apply gender-inclusive language throughout

Informal communications (social media, blogs):

• Context-dependent
• Generally use "vous"/"usted" for semi-formal
• May use "tu"/"tú" for very informal contexts

Video subtitles/transcripts (SRT files):

• Use the kobo-translation-srt skill extension
• All base rules apply PLUS subtitle-specific adaptations
• Key differences:
  • XLSForm terms: English only (no translations due to character limits)
  • Character limits: 35-42 characters per line ideal, 50 max
  • Natural spoken language (more conversational than written)
  • Chunked translation approach to preserve context
• Same formality levels as educational content (vous/tú)

Step 2: Check Terminology Category

🚨 Brand and product terms → See brand-terminology.md

• OFFICIAL translations must be used EXACTLY (KoboToolbox, Academy, User Plans, servers, Question Library, etc.)
• Pay special attention to:
  • Server names (require articles in French, specific wording in both languages)
  • Question Library (requires capital article in both languages)
  • Formbuilder (requires English + translation on first reference)
  • KoboCollect app name format

Form building and XLSForm → See form-building-terms.md

• Many terms must include English + translation in parentheses
• Video subtitles: English only (character limits)
• Examples: list_name (nom de la liste), cascading select (Sélection en cascade)

Question types and appearances → See question-types.md

• Question appearances in written content: English + translation
• Example: "vertical, picker (sélecteur), rating (notation)"

UI terminology → See ui-terminology.md

• OFFICIAL translations, capitalize per UI
• Common UI terms: FORMULAIRE/FORMULARIO, DONNÉES/DATOS, Brouillon/Borrador
• Flag any needed corrections in tracker

Data collection terms → See data-collection-terms.md

• Preferred translations, adapt for context
• Special rules for management, submissions, data collection

Course and learning platform → See course-terminology.md

• Preferred translations
• Context-specific adaptations allowed

Step 3: Apply Gender-Inclusive Language

Arabic: [To be specified based on project needs]

Step 4: Handle Technical Terms

XLSForm and form building terms that must stay in English:

• Written content: English followed by translation in parentheses on first use
• Video subtitles: English only
• Examples:
  • list_name (nom de la liste)
  • XML values (valeurs XML)
  • data column name (nom du champ)

Cascading select components: Always include English + translation approach:

"Pour chaque liste d'options, remplissez la colonne list_name (nom de la liste)."

Core Translation Principles

Localization over literal translation:

• Adapt idioms and expressions naturally
• Maintain technical accuracy
• Ensure clarity for new users

Consistency:

• Use same term for same concept throughout
• Align with KoboToolbox UI terminology
• Flag UI terminology corrections in tracker

Formatting:

• Maintain spacing, paragraphs, structure when possible
• Use concise sentences
• Follow target language punctuation conventions
• Avoid slang: "gonna" → "going to"
• Convert HTML heading tags to markdown format: <h2> → ##, <h3> → ###, etc.
• Preserve all other HTML tags and attributes (iframe, section, etc.)
• Keep markdown link syntax intact
• Don't translate image paths or URLs

Acronyms:

• First use: Full translation followed by acronym in parentheses
• If no common translated acronym exists, use English acronym
• Example FR: "l'Agence des Nations Unies pour les réfugiés (HCNUR)"
• Example ES: "Agencia de las Naciones Unidas para los refugiados (ACNUR)"

Plain language:

• Technical content must be beginner-friendly
• Avoid unnecessary jargon
• Prioritize clarity

Natural language flow:

• Don't force English sentence structure
• Adapt word order to target language conventions
• Use natural expressions, not literal translations

Common Translation Patterns

HTML and Markdown Elements

Preserve HTML structure:

• Keep all HTML tags intact EXCEPT heading tags: <iframe>, <section>, etc.
• IMPORTANT: Convert HTML heading tags to markdown headings:
  • <h1> → # (markdown h1)
  • <h2> → ## (markdown h2)
  • <h3> → ### (markdown h3)
  • <h4> → #### (markdown h4)
  • Example: <h2>Why KoboToolbox is unique</h2> → ## Por qué KoboToolbox es único
• Maintain non-heading attributes: dir="rtl", id, class, style, etc.
• Do NOT translate HTML attributes or parameters

Metadata and front matter:

• Preserve "Last updated" lines with dates and GitHub links
• Format: **Last updated:** <a href="[github-url]" class="reference">[date]</a>
• Keep the GitHub URL and class unchanged
• Do NOT translate "Last updated" text - keep in English

Links and cross-references:

• Preserve markdown link syntax: [Text](url.md)
• Internal documentation links (same language): Keep relative links as-is - they automatically resolve to the correct language folder
  • Example: In docs/es/article_a.md, a link [other article](article_b.md) correctly points to docs/es/article_b.md
• Cross-language reference links: Update the path to point to the correct language directory
  • From Spanish (docs/es/), link to:
    • English: ../en/filename.md → Example: [Read in English](../en/about_kobotoolbox.md)
    • French: ../fr/filename.md → Example: [Lire en français](../fr/about_kobotoolbox.md)
    • Arabic: ../ar/filename.md → Example: [اقرأ باللغة العربية](../ar/about_kobotoolbox.md)
  • From French (docs/fr/), link to:
    • English: ../en/filename.md
    • Spanish: ../es/filename.md
    • Arabic: ../ar/filename.md
  • From Arabic (docs/ar/), link to:
    • English: ../en/filename.md
    • Spanish: ../es/filename.md
    • French: ../fr/filename.md
• Cross-language link text:
  • English: "Read in English"
  • French: "Lire en français"
  • Spanish: "Leer en español"
  • Arabic: "اقرأ باللغة العربية"
• External links (https://...) translate the visible text but keep the URL unchanged
  • Example: [our mission](https://www.kobotoolbox.org/about-us/our-mission/) → FR: [notre mission](https://www.kobotoolbox.org/about-us/our-mission/)

Images:

• Keep image paths unchanged: ![image](images/about_kobotoolbox/usermap.png)
• Do NOT translate image file names or paths

YouTube embeds:

• Update language parameters for target language:
  • cc_lang_pref=fr for French
  • cc_lang_pref=es for Spanish
  • cc_lang_pref=ar for Arabic
  • hl=fr / hl=es / hl=ar
• Keep all other iframe attributes unchanged

Language-Specific Formatting

Title and heading conventions:

• English: Title case for main headings ("About KoboToolbox: Accessible Data Collection")
• French: Capitalize first word and proper nouns only ("À propos de KoboToolbox : Collecte de données accessible à toutes et tous")
• Spanish: Capitalize first word and proper nouns only ("Acerca de KoboToolbox: Recolección de datos accesible para todas las personas")
• CRITICAL: Always use markdown heading syntax (##, ###) NOT HTML tags (<h2>, <h3>)
• Note: Some titles may use h1 (#), others h2 (##) - follow the source document's pattern

Inclusive language in titles:

• French: "à toutes et tous" (to all, everyone - feminine and masculine)
• Spanish: "para todas las personas" (for all people)

Section headers:

• Use <h2> or <h3> tags for HTML format, or ## / ### for markdown
• French examples: "Pourquoi KoboToolbox est unique", "Soutenir l'impact à échelle mondiale"
• Spanish examples: "Por qué KoboToolbox es único", "Apoyamos el impacto global"
• Note natural language variations: ES "Apoyamos" (we support) vs EN "Supporting" (present participle)

Arabic (RTL):

• Wrap Arabic content in <section dir="rtl"> tags
• Keep heading IDs: <h1 id="ar">
• Cross-reference links stay OUTSIDE the RTL section
• Arabic titles are placed inside RTL section with proper heading markup

Heading levels:

• Maintain heading hierarchy (h1, h2, h3)
• In Arabic translations, the h1 is inside the RTL section
• Title may be rendered as h2 (##) in some contexts, h1 in others - follow source

French-Specific Rules

"Data collection":

• Default: "collecte de données" (general concept)
• Specific project data: "collecte des données"
• Not: "collecte de données d'enquête"

"Submission/Record/Response": Context-dependent, see data-collection-terms.md for full guide:

• Use "soumission" for data management contexts, UI, Data table
• Use "réponse" or "formulaire" when less technical, avoid confusion

"Upload":

• Primary: "importer"
• Context: "envoyer" (e.g., send a form)
• Not: "télécharger"

"View" (UI):

• "mode" (mode Tableau, mode Carte)
• Not: "affichage" or "aperçu" for UI elements

Website terms:

• "site web" not "site Internet"
• "web" lowercase: "formulaire web Enketo"

Verbs with object pronouns:

• French naturally places pronouns before verbs: "les rend" (makes them)
• Don't force English word order

Spanish-Specific Rules

"Management":

• Data/case management: "manejo" (manejo de datos, manejo de casos)
• Teams/projects: "gestión" (gestión de equipos, gestión de proyectos)

"Collect" (data):

• Use "recolectar" not "recopilar"

Gender-neutral when possible:

• Prefer "Se te dirigirá" over "serás dirigido/a"
• Use masculine when no neutral option: "los usuarios"

Natural word order:

• Spanish sentence structure may differ from English
• Example: "makes data accessible" → "permite que los datos sean accesibles" (not literal translation)

Cross-Language Rules

"Disaggregate":

• FR: "désagréger" (not "ventiler")
• ES: "desagregar"

"Press" (button):

• FR: "appuyer sur" (not "presser")
• ES: "click en"

"Case sensitive":

• FR: "sensibles à l'utilisation de majuscules et de minuscules" (not "sensible à la casse")
• ES: "distingue entre mayúsculas y minúsculas"

Organization and context-specific terms:

• "Social impact" → FR: "impact social" / ES: "impacto social"
• "Practitioners" → FR: "praticiens" (context: data collection practitioners = "mختصين في جمع البيانات" in Arabic)
• "Challenging settings" → FR: "environnements difficiles" / ES: "entornos desafiantes"

Adapting metaphors and expressions:

• Don't translate idioms literally
• Example: "accessible to/for" may require restructuring in target language
• French: "rendre accessible" (make accessible) rather than "être accessible à"

Terminology References

For detailed term-by-term translations, consult these reference files:

• brand-terminology.md - Brand terms, product names, user plans (OFFICIAL) - READ THIS FIRST
• form-building-terms.md - Form building, XLSForm, cascading selects (OFFICIAL)
• question-types.md - Question types and appearances (PREFERRED for types, special rules for appearances)
• ui-terminology.md - Formbuilder and KoboCollect UI (OFFICIAL) - READ THIS SECOND
• data-collection-terms.md - Data collection concepts (PREFERRED)
• course-terminology.md - Learning platform and course content (PREFERRED)

Translation Decision Tree

START: Do I see ANY of these terms in the source text?
├─ Server names (Global Server, EU Server)?
│  └─ 🚨 STOP → Open brand-terminology.md → Use EXACT translation with articles
│
├─ "Question Library"?
│  └─ 🚨 STOP → Must be "La bibliothèque de questions" / "La biblioteca de preguntas" (capital L)
│
├─ "Formbuilder"?
│  └─ 🚨 STOP → First reference must include English in parentheses
│     ES: "editor de formularios de KoboToolbox (Formbuilder)"
│     FR: "l'interface de création de formulaires KoboToolbox (KoboToolbox Formbuilder)"
│
├─ UI element (button, tab, menu - like DEPLOY, NEW, FORM, DATA)?
│  └─ Check ui-terminology.md → Use OFFICIAL translation → Match UI capitalization
│
├─ Draft / Brouillon / Borrador?
│  └─ Capitalize in UI contexts: "Brouillon" / "Borrador"
│
├─ XLSForm technical term (list_name, cascading select)?
│  └─ Written: English + translation in parentheses
│     Subtitles: English only
│     See form-building-terms.md
│
├─ Question appearance (minimal, picker, rating)?
│  └─ Written: English + translation in parentheses
│     Subtitles: English only
│     See question-types.md
│
├─ Form building or data collection term?
│  └─ Check if OFFICIAL or PREFERRED
│     Apply OFFICIAL exactly; adapt PREFERRED for context
│     See relevant reference file
│
├─ Course or educational content?
│  └─ Use PREFERRED translations
│     Apply appropriate pronoun formality
│     See course-terminology.md
│
└─ Unsure about gender inclusivity?
   └─ Use gender-neutral language
      FR: vous + parenthetical markers (e)
      ES: neutral constructions or tú with "se te"

Enhanced Quality Checklist

Before finalizing translation:

** CRITICAL - Brand & UI Terms:**

• All server names use EXACT translations from brand-terminology.md (with articles!)
• "Question Library" has capital article: "La bibliothèque" / "La biblioteca"
• Formbuilder includes English on first reference
• All UI elements (buttons, tabs) match ui-terminology.md exactly
• UI terms capitalized correctly (Brouillon, Borrador, etc.)

Structure & Formatting:

• HTML heading tags converted to markdown (## for h2, ### for h3, etc.)
• All other HTML tags preserved and unchanged (iframe, section, etc.)
• Internal documentation links kept as relative paths (they auto-resolve correctly)
• Cross-language reference links updated to use directory paths (../en/, ../es/, ../fr/, ../ar/)
• External links: translated text, unchanged URLs
• Image paths unchanged
• YouTube embed language parameters updated (cc_lang_pref, hl)
• Arabic content wrapped in <section dir="rtl"> tags
• Heading hierarchy maintained

Language & Style:

• Correct formality level (vous/tu, usted/tú) for content type
• Gender-inclusive language throughout (especially Spanish double forms)
• XLSForm/technical terms follow English + translation pattern
• Consistent terminology (same term for same concept)
• Plain language, beginner-friendly
• Proper acronym handling (full term + acronym first use)
• Target language punctuation conventions
• No slang or colloquialisms
• Natural word order (not forced English structure)

Translation Error Examples

Real-World Translation Patterns

Example from actual translations:

Source English: "KoboToolbox makes high quality data accessible to social impact organizations worldwide."

Key observations:

• French naturally restructures: "makes data accessible" → "rend les données accessibles" (makes the data accessible)
• Spanish restructures differently: "permite que los datos sean accesibles" (permits that the data be accessible)
• Both translations adapt to natural target language expressions rather than forcing English structure

Source English: "Designed by data collection practitioners specifically for challenging settings"

✅ CORRECT Arabic: "مُصممة من قبل مختصين في جمع البيانات للتعامل مع الظروف الصعبة بشكل خاص"

Key observations:

• Spanish uses gender-inclusive "personas profesionales" instead of literal "practitioners"
• Spanish adds "Fue" (was) for natural past tense flow
• Arabic restructures significantly: "designed... for dealing with difficult circumstances especially"
• All prioritize natural expression over literal translation

Example 1: Server Names

Source: "Most users sign up for an account on our Global KoboToolbox Server."

Errors fixed:

1. Removed "de KoboToolbox" (not in official name)
2. Added gender inclusivity: "los/as usuarios/as"

Errors fixed:

1. Added definite article "Le" (capitalized)
2. Added gender inclusivity: "utilisatrices et utilisateurs"

Example 2: Question Library

Source: "Build a form using a template from the question library."

Error fixed: Capitalized "L" in "La" (brand feature name)

Example 3: Formbuilder First Reference

Source: "Create a new form using the KoboToolbox Formbuilder."

Error fixed: Added English term in parentheses on first reference

Example 4: HTML Headings to Markdown

Source (English with HTML tags):

<h3>Why KoboToolbox is unique</h3>

KoboToolbox is hosted and maintained by the international nonprofit organization...

<h3>Supporting global impact</h3>

KoboToolbox is the most widely used data collection tool...

Apoyamos el impacto global

KoboToolbox es la herramienta de recolección de datos más utilizada...

**Error fixed:** Converted HTML `<h3>` tags to markdown `##` (since h3 corresponds to ##)

**Key observations:**
- Always convert HTML heading tags to markdown format
- Maintain the heading level: h1→#, h2→##, h3→###, h4→####
- Keep all other HTML tags (iframe, section, etc.) intact

### Example 5: Internal and Cross-Language Links

**Source (English file in `docs/en/p_codes.md`):**
```markdown
# Including P-Codes in the Output Data

[Lire en français](../fr/p_codes.md) | [Leer en español](../es/p_codes.md)

If using cascading lists, please [follow the instructions](cascading_select.md)
for cascading selects.

Key observations:

• Internal doc link cascading_select.md stays as-is (relative path auto-resolves to docs/es/cascading_select.md)
• Cross-language links updated to use directory structure (../en/, ../fr/)
• Link text translated appropriately for each language

Errors:

• Cross-language links don't specify the language directory
• Internal link incorrectly uses _es suffix instead of relying on relative path

Example 6: Natural Language Flow

Source: "To support our nonprofit users, we provide our tools for free under the Community Plan."

Key observations:

• French: "for free" → "gratuitement" (as adverb, not "pour gratuit")
• French: "under the plan" → "dans le cadre du plan" (in the framework of)
• Spanish: "for free" → "de forma gratuita" (in free form)
• Spanish: "nonprofit users" → "usuarios sin fines de lucro" (different word order)

Notes

Reporting issues: If UI terminology needs correction, flag in comment and record in appropriate tracker or communications channel.

Working document: This is a living guideline. Feedback welcome. More languages and terms will be added.

Reference documents:

• KoboToolbox Academy Course Style Guide
• Essentials Translation Glossary (Master)
• Transifex UI translations
• UN Women Gender Inclusive Language (Spanish)
• Clear Global terminology documents