Translation work arrives as a table far more often than as anything purpose-built. A key column, the source language, a column per target language, and some columns that are not translations at all.
It is a reasonable format. It survives being emailed, it opens anywhere, and a translator does not need an account to use it. What it does not do is understand what any of the columns mean, and that is where the trouble starts.
The shape of the file
Five kinds of column, in roughly this order:
- The key — the identifier the software looks the string up by.
checkout_button_label, or a number. This column is not text for humans and must survive untouched. - The source language — what the translator reads from. Usually English, and it is not theirs to edit; a change here silently desynchronises every other column.
- The target languages — one per locale, the columns being filled in.
- Comments — developer notes, translator questions, replies. Prose about the string rather than the string.
- Metadata — status, screen name, character limit, the file the string came from.
The distinction between the last two and the target languages is the one a spreadsheet cannot make on its own, and the one that matters most.
How a language column is recognised
By its header, and headers are inconsistent in predictable ways. A tool that only accepts a bare ISO code will miss most real files.
There are three families to handle. Plain codes — en, es, ja — are the easy case. Regional variants — pt-BR, zh-Hans, es-419 — carry a script or a region after a separator, and dropping the suffix would merge Brazilian and European Portuguese into one column that is neither. Spelled-out names — Spanish, Japonés — appear whenever the file was prepared for people rather than for a parser.
On top of that, headers arrive decorated: [EN], text_en, en (US), EN_translation. These are all the same language wearing different clothes, and the only workable approach is to strip the decoration down to a code before deciding.
This site’s editor also matches accented and unaccented forms of written-out names, because a header saying Japonés and one saying Japones are the same column and only one of them was typed carefully.
The columns that are not translations
A comment column rendered as an editable translation cell is worse than useless — it invites someone to translate a note that was meant to be read, and it counts toward a completeness figure it has nothing to do with.
The header words that mark commentary are a short list in any language: comment, note, remark, context, instruction, feedback, reply, and their equivalents. In files from Japanese studios those headers are just as likely to be コメント, 備考 or 返答, and a tool that only checks English words will treat three columns of developer correspondence as untranslated strings.
Metadata is the other group — id, status, screen, file, maxlength, limit. These need to be visible, because a character limit is exactly what a translator needs to see, but they are not work to be done.
Get this wrong and every number you compute afterwards is wrong with it. A file reported as 60% translated when three of its “languages” are comment columns tells you nothing.
Where the spreadsheet works against you
Four specific failures, all of them common:
The key column gets destroyed. Keys look enough like data for Excel to convert them: a leading zero disappears, MAR1 becomes a date. The software then cannot find the string, and the translation that was done correctly is lost behind a key that no longer matches.
Completeness is invisible. A spreadsheet will tell you a column has 1,200 non-empty cells. It will not tell you that 300 of them are still the English source text, which is not the same as being translated.
There is no safe merge. Two translators working on two copies produce two files, and reconciling them is manual. This is the single strongest argument for a real localisation platform once a project passes a certain size.
The encoding goes. A file with Japanese, Korean and accented Latin in it is exactly the file that turns into mojibake when opened without the right encoding — and, unlike a key, damaged text does not announce itself in a language you cannot read.
Conventions that make it survivable
If the table is what you have, a few decisions remove most of the pain:
- Put the key first and never sort by anything else. Sorting a translation table by a target language scrambles the correspondence between rows and keys if anything downstream assumes order.
- Name language columns with codes, not names.
pt-BRis unambiguous;Portugueseis a question. - Keep comments in clearly named columns and never in the same column as a translation.
- Agree the encoding and line endings once, and re-export with the same settings every time. UTF-8 throughout, and a byte order mark only if someone genuinely opens it in Excel.
- Send TSV rather than CSV when the content is prose. Translated text is full of commas and rarely contains tabs, so the delimiter stays out of the way — the trade-off is covered in TSV vs CSV.
Doing it here
The editor on this site recognises this shape on open: it looks at the headers, works out which columns are languages, which is the source, and which are commentary or metadata. When it finds a key and at least two language columns it switches into a translation mode built around that layout.
The source column becomes read-only, because editing what the translator reads from is almost never intended. Comment columns are presented as notes attached to the row rather than as cells to fill in. Progress is reported per language, and what counts as translated is a question with more than one answer.
Nothing is uploaded: the file is read and written by your browser, which for a translation hand-off under an agreement about where the content may go is not a small detail. The TSV and CSV translation file editor page covers the rest of what that mode does.