Agent-Skills.md

Agent Skills: KoboToolbox Translation & Localization

Translation and localization guidelines for KoboToolbox content in French, Spanish, and Arabic. Use when translating KoboToolbox materials including: (1) Academy courses and educational content, (2) User interface text and documentation, (3) Support articles, (4) Marketing materials, (5) Form building terminology, or (6) XLSForm technical terms. Covers tone, pronouns (tú/usted, tu/vous), gender-inclusive language, and official translations for brand terms and UI elements.

UncategorizedID: joshuaberetta/kobo-translation-test/kobo-translation

Install this agent skill to your local

pnpm dlx add-skill https://github.com/joshuaberetta/kobo-translation-test/tree/HEAD/skills/kobo-translation

Skill Files

Browse the full folder contents for kobo-translation.

Download Skill

Loading file tree…

skills/kobo-translation/SKILL.md

Skill Metadata

Name
kobo-translation
Description
"Translation and localization guidelines for KoboToolbox content in French, Spanish, and Arabic. Use when translating KoboToolbox materials including: (1) Academy courses and educational content, (2) User interface text and documentation, (3) Support articles, (4) Marketing materials, (5) Form building terminology, or (6) XLSForm technical terms. Covers tone, pronouns (tu/usted, tu/vous), gender-inclusive language, and official translations for brand terms and UI elements."

KoboToolbox Translation & Localization

Overview

Translate KoboToolbox content in French, Spanish, and Arabic with consistent terminology, appropriate tone, and cultural adaptation.

For Video Subtitles: Use the kobo-translation-srt skill extension for subtitle-specific guidelines.

Translation approach:

  • NEW FILES: Translate complete document with consistent terminology
  • UPDATES: Translate only changed content (diff-based to reduce translation noise)

CRITICAL: Pre-Translation Checklist

BEFORE translating, check these reference files:

  1. brand-terminology.md - Server names, Question Library, Formbuilder
  2. ui-terminology.md - Button names, tabs, capitalization
  3. article-titles.md - Official article titles in all languages (OFFICIAL — verbatim)

Translation Types

  • OFFICIAL - Use EXACT translation (brand terms, UI elements, XLSForm)
  • PREFERRED - Adapt for context (general terminology, courses)

XLSForm Terms

  • Never translate: worksheet names, column names, type values, appearances, functions
  • Written content: English + translation in parentheses
  • Subtitles: English only

Example: `list_name` (nom de la liste / nombre de la lista)

Spanish Critical Rules

🚨 ALL Spanish documentation, UI text, and support articles use informal tú. NEVER use usted.

| ✅ Correct (tú) | ❌ Wrong (usted) | |---|---| | haz clic | haga clic | | tu cuenta | su cuenta | | tu formulario | su formulario | | puedes | puede | | tienes | tiene | | ve a Configuraciones | vaya a Configuraciones |

If you find yourself writing "su", "usted", "haga", "vaya a" — stop and rewrite in tú.

Also: use "clic" (not "click"): "haz clic en el botón".

Spanish Formality

Use tú (informal) throughout all Spanish documentation and UI text.

| Content Type | Spanish | |---|---| | UI / Documentation | tú | | Courses / Support | tú, ustedes (plural) | | Formal communications | usted |

Spanish Gender-Inclusive Language

Use standard masculine plural as the generic form for documentation clarity. Avoid slash notation (los/as).

  • "los usuarios" — NOT "los/as usuarios/as"
  • "el usuario" — NOT "el/la usuario/a"
  • "los participantes" — NOT "los/as participantes"

Examples: "all users" → "todos los usuarios"; "Project administrators" → "administradores del proyecto"

Spanish Language Rules

  • ALWAYS tú — NEVER usted (see critical rule above)
  • "clic" not "click": "haz clic en"
  • "recolectar" (not "recopilar")
  • "manejo" for data/case management
  • "gestión" for teams/projects

Spanish XLSForm Worksheet Tab Labels

When the source has a bold worksheet label like **survey worksheet**, **choices worksheet**, or **settings worksheet**, translate it using the pattern **hoja [name]** — keep the sheet name in English, prefix with the translated word only:

| English | Spanish | |---------|---------| | **survey worksheet** | **hoja survey** | | **choices worksheet** | **hoja choices** | | **settings worksheet** | **hoja settings** |

🚨 Do NOT write **hoja de trabajo survey** — that is wrong. The sheet name stays in English.

Spanish Quality Checklist

  • [ ] tú throughout — no "su", "usted", "haga" anywhere
  • [ ] "clic" not "click"
  • [ ] standard masculine plural — "los usuarios" not "los/as usuarios/as"
  • [ ] Worksheet labels use **hoja survey** not **hoja de trabajo survey**
  • [ ] Article H1 matches article-titles.md Spanish entry exactly
  • [ ] Cross-referenced article titles match article-titles.md Spanish entries exactly

French Critical Rules

🚨 The first mention of the Formbuilder in any French article must include the English name in parentheses:

interface de création de formulaires KoboToolbox (KoboToolbox Formbuilder)

Subsequent mentions can use the short form "Formbuilder" or "l'interface de création de formulaires".

French Formality

Use vous throughout all French documentation and UI text.

| Content Type | French | |---|---| | UI / Documentation | vous | | Courses / Support | vous | | Formal communications | vous |

French Gender-Inclusive Language

Use standard masculine plural as the generic form for documentation clarity. Avoid parenthetical constructions like "(rice)".

  • "les utilisateurs" — NOT "les utilisateur(rice)s"
  • "l'utilisateur" — NOT "l'utilisateur(rice)"
  • "un utilisateur" — NOT "un(e) utilisateur(rice)"

Examples: "all users" → "tous les utilisateurs"; "Project administrators" → "administrateurs du projet"

Exception: fixed compound nouns like "interface utilisateur" and "nom d'utilisateur" must stay as-is.

French Language Rules

  • "collecte de données" (not "des données" unless specific)
  • "importer" for upload (not "télécharger")
  • "appuyer sur" for press (not "presser")
  • "Introduction à..." for "Getting started" (not "Débuter avec")
  • First Formbuilder mention: interface de création de formulaires KoboToolbox **(KoboToolbox Formbuilder)**

French XLSForm Worksheet Tab Labels

When the source has a bold worksheet label like **survey worksheet**, **choices worksheet**, or **settings worksheet**, translate it using the pattern **onglet [name]** — keep the sheet name in English, prefix with the translated word only:

| English | French | |---------|--------| | **survey worksheet** | **onglet survey** | | **choices worksheet** | **onglet choices** | | **settings worksheet** | **onglet settings** |

🚨 Do NOT write **hoja survey** or **hoja settings** in French — those are Spanish forms. French always uses **onglet**.

French Quality Checklist

  • [ ] vous throughout
  • [ ] First Formbuilder mention includes (KoboToolbox Formbuilder) parenthetical
  • [ ] standard masculine plural — "les utilisateurs" not "les utilisateur(rice)s" — throughout
  • [ ] Worksheet labels use **onglet survey** not **hoja survey**
  • [ ] Article H1 matches article-titles.md French entry exactly
  • [ ] Cross-referenced article titles match article-titles.md French entries exactly

Formatting Rules

  • Convert HTML headings to markdown: <h1> → #, <h2> → ##, <h3> → ###
  • Malformed hierarchy fix: If the source has <h3> directly under <h1> with no <h2> in between, render it as ## — not ###. Example: source is # Title then <h3>Section</h3> → output must be # Title then ## Section. Do NOT output ### Section in this case.
  • Keep other HTML tags intact
  • Internal links: keep as-is (auto-resolve)
  • Cross-language links: use ../en/, ../fr/, ../es/, ../ar/
  • Images/URLs: don't translate paths
  • YouTube embeds: update cc_lang_pref and hl parameters

🚨 CRITICAL: Article H1 Heading

The article's own # H1 must be a faithful translation of the English H1 — do not invent a shorter or restructured variant.

The article-titles.md file lists the official titles for each article. The H1 of the article being translated must match its entry in article-titles.md exactly. If no entry exists, translate faithfully and flag it.

Article Title Consistency

When translating any article that references another article by title:

  1. Look up the target article's filename in article-titles.md
  2. Use the exact title listed for the target language — never translate it yourself
  3. If a title is missing from the file, flag it rather than guessing

This is critical: articles cross-reference each other, and titles must be identical across all languages.

Documentation Guidelines

Do not translate XLSForm terms

XLSForm elements such as worksheet names, column names, question types, appearances, boolean operators, functions, and parameters must remain exactly as they appear in the original article. They should be explained in the course or documentation text when they are used for the first time, then the English term should be used throughout.

The concept can be translated as long as the XLSForm component stays in English. For example: “La colonne choice_filter est utilisée pour mettre en place des filtres de choix.”

In general, terms formatted in code should not be translated, unless they are placeholder text, such as label::idioma (código). In XLSForm tables, names, labels, and list_names for questions and choices can be translated.

Do not translate error messages

Error messages must remain in English because they are often untranslated in the KoboToolbox UI. Keep the error message exactly as it appears in the original article.

Keep article titles and section headers short and direct

Prioritize idiomatic, commonly used French phrasing that conveys the meaning (i.e., how a native speaker would say it), rather than literal word-for-word translations. Example: “Getting started with XLSForm” -> “Créer des formulaires avec XLSForm”

Do not include parentheses in titles or headers. If a term requires explanation, define it in the article text instead.

Example: “Comenzando con el editor de formularios de KoboToolbox (Formbuilder)” → “Comenzando con el KoboToolbox Formbuilder”.

Avoid complicated gender-inclusive constructions for clarity

While using gender-neutral language whenever possible and adapting phrasing as needed to ensure inclusivity in the target language, avoid complex gender-inclusive constructions (e.g., los/as usuarios/as) for clarity in documentation. Use standard masculine plural forms in languages where this is conventional.

Examples: “all users” → “todos los usuarios” -> “tous les utilisateurs” ; “Project administrators” -> “administrateurs du projet”

Preserve all formatting from the original article

Keep boldface, code formatting, lists, note boxes, table structures, and link placement exactly as in the source.

Use exact UI terminology

When translating names of UI elements such as buttons, tabs, pages, and views, use the exact term as defined in this guide or in Transifex. Match capitalization and styling exactly.

Maintain consistency with the Documentation Style Guide

Follow Kobo’s conventions for tone (informational and neutral), sentence structure (short and clear), terminology, and capitalization of brand terms.

Maintain terminology consistency across articles

Use the same approved translation, capitalization, and formatting for key terms in all articles, and do not introduce alternative synonyms for the same concept.

Question types and question appearances

When referring to question types in the Formbuilder, use the translated question type name from the UI. When referring to question types in XLSForm, keep the English XLSForm term in monospaced code formatting.

For question appearance names, keep the English term because it is required by both XLSForm and the KoboToolbox Formbuilder. When specified in the glossary, follow the English appearance name by the translation in parentheses to support comprehension. For example: Pour la question de type Intervalle, vous pouvez choisir entre les options d'apparence vertical, picker (sélecteur), rating (notation), et distress (thermomètre).

Terminology References

OFFICIAL — Must Use Verbatim

PREFERRED — Can Adapt for Context

Quality Checklist

Brand & UI:

  • [ ] Server names with correct articles
  • [ ] Capital L on Question Library (see brand-terminology.md)
  • [ ] UI terms match exact capitalization

Formatting:

  • [ ] HTML headings → markdown (h3 under h1 with no h2 → rendered as ##)
  • [ ] Cross-language links updated
  • [ ] Image paths unchanged
  • [ ] YouTube language parameters set

Language:

  • [ ] Standard masculine plural throughout — avoid slash/parenthetical gender constructions
  • [ ] XLSForm terms in English + translation
  • [ ] Natural word order

Article titles:

  • [ ] Article H1 matches the article-titles.md entry exactly
  • [ ] Cross-referenced article titles match article-titles.md exactly

Updating This Skill

Source files in sources/:

  • glossary.xlsx - Cached copy of the Google Sheet (offline fallback)
  • doc-guidelines.md - Cached Documentation Guidelines from the Google Doc
  • style-guide.md - Style guidelines
  • workflow-rules.md - Workflow/checklists
  • language-rules.md - Language-specific rules

To refresh from live sources:

python scripts/fetch_glossary.py        # pull latest xlsx from Google Sheets
python scripts/fetch_doc_guidelines.py  # pull Documentation Guidelines from Google Doc
python scripts/regenerate_skill.py      # rebuild skill from cached copies

Or combined:

python scripts/sync_and_update.py --fetch