Aller au contenu

Excel content import

Version française
← Back to index

Overview

Excel import is the primary method for loading content (words and phrases) for a language. The file is parsed server-side using the xlsx library, validated, and then cards and items are created in the database in batches.

⚠️ Required format: files must be in Excel 2007+ (.xlsx) format. The formats .xls, .csv, .ods are not accepted.

Template — Word cards

Required columns

Column name Type Description
numero_carte Integer Card number (starts at 1, no gaps)
position Integer Position within the card (1 to 6)
texte_original Text Word in the African language
traduction Text French translation
theme Text Card theme (e.g. "Famille", "Nourriture")

Word template example

numero_carte position texte_original traduction theme
1 1 Baaba Père Famille
1 2 Yaaya Mère Famille
1 3 Biraado Enfant Famille
1 4 Gorko Homme Famille
1 5 Debbo Femme Famille
1 6 Esraajo Frère Famille
2 1 Kosam Lait Nourriture
2 2 Mburu Pain Nourriture
... ... ... ... ...

Rules for words

  • 6 items per card (positions 1 to 6) — all positions must be present
  • Uniqueness: the combination (numero_carte, position) must be unique
  • No gaps: consecutive card numbers (1, 2, 3…), positions 1 to 6 for each card
  • Theme: identical for all items in the same card (the theme is attached to the card, not the item)

Template — Phrase cards

Required columns

Column name Type Description
numero_carte Integer Card number (starts at 1, no gaps)
texte_langue_à_traduire Text Question in the African language (position 1, Lot 1)
traduction_texte_langue Text French answer (position 2, Lot 1)
texte_français_à_traduire Text Question in French (position 3, Lot 2)
traduction_texte_français Text Answer in the African language (position 4, Lot 2)

Phrase template example

numero_carte texte_langue_à_traduire traduction_texte_langue texte_français_à_traduire traduction_texte_français
1 Noy def? Comment vas-tu ? Comment vas-tu ? Noy def?
1 Jaamm rek Bien seulement Bien seulement Jaamm rek
2 Ay ngonaa? Où vas-tu ? Où vas-tu ? Ay ngonaa?
2 Ñaare ma Au marché Au marché Ñaare ma
... ... ... ... ...

Note: one row per conversation exchange (question + answer). The application automatically generates 4 items from each row.

Automatically generated structure

For each phrase row, the application creates 4 items:

Position Lot Content Audio required
1 1 texte_langue_à_traduire (African language) ✅ Yes
2 1 traduction_texte_langue (French) ❌ No
3 2 texte_français_à_traduire (French) ❌ No
4 2 traduction_texte_français (African language) ✅ Yes

Encoding and special characters

  • Save your Excel file in UTF-8 for African characters (ñ, ɓ, ŋ, ɗ, ƴ, etc.)
  • Excel handles encoding automatically if you create the file in Excel or Google Sheets
  • If you create from a text editor, ensure UTF-8 encoding

Best practices before import

  1. First row = headers: respect the exact column names (case-sensitive)
  2. No empty cells in required columns
  3. No gaps in numbering: card 1, 2, 3, 4… (no jump from 1 to 3)
  4. 6 positions per word card: all positions 1 to 6 present
  5. Cross-check: compare the total number of rows with your data source
  6. Character encoding: test with a few special characters in a cell

Common errors and messages

Error message Cause Solution
"Colonne manquante : [name]" Incorrect or missing column name Check the exact spelling of the headers
"Carte incomplète : carte [n]" Fewer than 6 positions for a word card Add the missing positions
"Position en double : carte [n], position [p]" Two items with the same card number and position Remove the duplicate
"Format de fichier invalide" Non .xlsx file Save as Excel 2007+
"Numéro de carte invalide : [n]" Non-numeric value in numero_carte Check the column cells
"Texte original vide : carte [n], position [p]" Empty cell in texte_original Fill in all required cells
"Trop de lignes (max 5000)" File too large Split the import into multiple files

What happens if the import fails?

If an error is detected before database creation: - No cards are created (atomic validation) - The error message specifies the problematic row and column - Fix the file and retry

If the error occurs during creation (rare): - Already created cards remain in the database - Retry the import: duplicates are ignored (uniqueness constraint in the database)

Updating existing content

The import is non-destructive: it adds cards to the language. It does not delete or modify existing cards.

To modify an existing card, use the card editor.

Next steps