Adding a language and importing translations

For: comrce staff with the Super Admin role who maintain the product's languages·Requires: The Super Admin role·Screenshots show sample data

Every text in comrce Hub, from a button label to an error message, comes from one translation file per language. To offer a new language or fix wording, you don’t wait for a release. As a Super Admin, you work in two steps. First add the language code, then import a CSV file with the texts.

Both happen under Languages. The result appears in every user’s language selector under Settings.

What it does

Texts change all the time: a new page needs labels, a German term reads wrong, a partner market needs Polish. Without the import, each change would need a new release of comrce Hub. With it, comrce staff publish texts on their own.

comrce Hub keeps one published text file per language. Adding a language creates an empty entry. An import replaces the file of every language column in the CSV whose language exists. Missing texts fall back to English. With it:

• You offer a new interface language to staff and customers. Setting it up in three steps.
• You correct or extend texts in any language with one file. The CSV file.
• You see which languages exist and when each was last imported, and you open each published file. Languages in the Languages list.
• Users pick the language under Settings, and their choice is saved for their account. Languages in the Settings language selector.
• You remove a language that is no longer offered. Delete.

Every step appears under Logs as Language created, Translations imported or Language deleted. The import entry names the file and which languages were and were not updated.

Before you start

Requirement	Details
Role	The Super Admin role. Other staff roles see no Languages entry.
A complete CSV	Column 0 holds the dotted text keys, each following column one language. Start from the current texts so that no key is lost, because the import replaces each language’s whole file.
Two-letter language codes	The import accepts no other codes. See the language code setting.
A spreadsheet tool that saves UTF-8 CSV	Commas as separators, quotes around values that contain commas.
Cost	None.

Good to know

Marketplace texts for sections, services and partners are not part of this import. They have a separate file per language. You import them under Marketplace. comrce Hub combines both files when it serves a language.

Understanding languages and fallback

State of a language	In the list	What users who choose it see
Added, never imported	A dash in the date column, no file arrow	English texts throughout
Imported with every key	Date of the last import, file arrow	The language’s own texts
Imported, some cells empty	Date of the last import, file arrow	The language’s texts, English where a cell was empty
Deleted	Not listed	English. The language leaves the selector at their next page load.

How comrce Hub decides

• English is the base. Every language is built on top of the English file. A key missing in the chosen language shows its English text.
• An import replaces, it does not merge. For each language column whose code exists, the file is replaced by exactly the keys in the CSV. A key that was in the old file but not in the CSV is gone from that language.
• Unknown codes are skipped. A column whose code has not been added is ignored, and the import still reports success.
• Codes are compared in lower case. DE in the header is treated as de.
• Empty cells are left out. An empty cell creates no empty text. The key falls back to English.

What does not get imported

• Rows with an empty first column, and empty lines.
• Columns of languages that do not exist yet.
• Regional codes such as en-US or pt-BR, and three-letter codes. The whole file is refused with Invalid language code in header.
• Values that run over several lines. The file is read line by line, so a line break inside a value splits the row.

Setting it up in three steps

1. Add the language. On Languages, select Add language. Type the two-letter code, for example pl, and confirm withCreate. The message Language has been added successfully. appears, and the list shows the language without a date.

   

   Step one adds the code. Use the two-letter ISO code, because the import accepts only those.

   What this screenshot shows

   Screen

   Translations

   Highlighted

   “Language code”: the submit button creates the language row

   Also visible

   Create button enabled

   Purpose

   creating the language before its import

2. Prepare the CSV. Put the dotted keys in the first column. Add a column headed pl next to the existing en and de columns, and fill in the Polish texts.

3. Import it. Select Update translations, then Choose file, and pick the file. Confirm withUpload. The message Translations imported successfully. appears, the dialog closes and the dates change.

   

   Check the file name before you upload. The file replaces the texts of every known language column it contains.

   What this screenshot shows

   Screen

   Translations

   Highlighted

   “hub-translations-2026-03.csv”: the upload button sends the file to the import

   Also visible

   CSV format rules; Upload button enabled

   Purpose

   a translations file ready to import

Add the language before you import it

A CSV column whose language does not exist yet is skipped. So add the language first, then import. Afterwards, check each language’s date: an unchanged date means it was skipped.

You can start with a few translated pages. Untranslated texts show in English, so nothing breaks. Each import must contain every key you want to keep.

Every setting, explained

The feature has three inputs, all on the Languages page. The ones that cause the most trouble come first.

CSV file

Where

The dialog Update translations: Choose file, thenUpload at the bottom right. The dialog lists the rules and a minimal example.

What

A .csv file of up to 50 MB. Other file types are refused with Selected file must be a CSV (.csv). The first line is the header: any title in column 0, language codes after it.

The file is refused, and nothing is published, with one of these messages:

• Empty CSV.
• CSV must have at least two columns: key and at least one language column.
• No language columns detected.
• Invalid language code in header.

Keys are split at the dots into the nested structure the app reads. Values may contain commas inside double quotes, and "" stands for one quote character.

Why

One file for all languages keeps the keys aligned. The same row holds a text in every language.

Do	Don’t
Start from the complete current texts and change only what you need	Upload a file with only the ten keys you changed. Every other key of those languages falls back to English.
Keep en in the file whenever you change English	Delete rows you did not touch
Quote values that contain commas	Put line breaks inside a value
Use two-letter column codes	Use en-US or Polish as a header

A header that is not a two-letter language code stops the whole import. Nothing is published.

What this screenshot shows

Screen

Translations

Highlighted

“Invalid language code in header.”: none; the file selection was cleared

Also visible

File selection reset to no file

Purpose

the import refused because of the header row

Language code

Where

The field Language code in the dialog Add language. Saved withCreate at the bottom right of the dialog.

What

Required (Code is required.). Spaces are removed as you type. The dialog accepts two or three lower-case letters, optionally followed by a dash and two upper-case letters. Anything else shows Use ISO code like 'en', 'de', or 'en-US'.

The code is stored in lower case. An existing code is refused with Language code already exists. The display name is the translated language name for that code, and codes without one show a raw key.

Why

The code links the language to its column in the CSV and to each user’s saved language. Use the two-letter code, because the import accepts nothing else.

Code typed	Dialog	Import accepts a column with it
pl	accepted	yes
PL	refused, format	–
fil	accepted	no, invalid language code
en-US	accepted, stored as en-us	no, invalid language code
pl_PL	refused, format	–

A new language has no file yet. The dash in Updated date tells you the import is still due.

What this screenshot shows

Screen

Translations

Highlighted

“pl”: none until a CSV with a pl column is imported

Also visible

7 languages; pl has no updated date and no file link

Purpose

the state between creating a language and importing its texts

Delete

Where

Delete in the language’s row, confirmed in the dialog Delete translation.

What

Removes the language row and its published files, both the general texts and the Marketplace texts. The language leaves the selector at each user’s next page load, and users who had chosen it get English. Nothing stops you from deleting English, and deleting en removes the base every other language is built on.

Why

A language you no longer maintain should not be offered with outdated texts.

How the settings combine

Language added	In the CSV header	Result of the import
yes	yes	File replaced, updated date set
yes	no	Unchanged
no	yes	Column skipped, success reported anyway
no	no	Nothing happens

Languages in the Languages list

The list shows each language with Code, Display name and Updated date, seven per page, sorted by code.

Indicator	Meaning
A date in the updated column	The time of the last import that included this language
A dash	The language was added but never imported
The arrow at the end of the row	Opens the published text file in a new browser tab

Why: the updated date is the quickest proof that an import reached a language.

Only the languages in the file get a new date. The others are untouched.

What this screenshot shows

Screen

Translations

Highlighted

“pl”: the arrow opens the published JSON file

Also visible

de, en, pl updated at the fixed clock time; es, fr, it, nl unchanged

Purpose

the result of an import

Languages in the Settings language selector

Where

Settings in the account menu, the language selector in the Account section. Customers have the same selector.

What

Lists every language that exists under Languages, imported or not, by its translated name. Choosing one switches the interface at once and saves the choice for the account. The list is read when comrce Hub loads, so a language added a minute ago appears after a page reload.

Why

Adding a language also offers it. Plan the import before you add a language in production.

• Add pl → after reloading, staff and customers can pick Polish. They see English until the import.
• Import pl → users who already chose Polish see Polish texts after their next page load.
• Delete pl → users who chose Polish see English, and Polish leaves the selector.

A language added on the Languages screen appears in everyone's language selector, imported or not.

What this screenshot shows

Screen

Settings

Highlighted

“Polish”: switches the interface language and saves it for the account

Also visible

Options: German, English, Polish

Purpose

where an added language shows up for users

Adding a language publishes it

A new language appears in every customer’s selector before any text exists for it. Add it only when the import is ready.

What you need to know

Topic	Fact
When users see changes	After their next page load. A browser that stays open keeps the texts it loaded.
Audit	Adding a language, every import and every deletion are logged with the Super Admin who acted.

Frequently asked questions

General

Who can add languages and import translations?

Only staff with the Super Admin role. The entry Languages is hidden from every other role. A direct link shows them You do not have permission to view this page.

Why does the sidebar say Languages and the tab say Translations?

The sidebar entry, the page heading and the tab title use different labels for the same page under Languages. In German the heading reads Sprachen and the tab Übersetzungen. It is one page.

Does importing translations change Marketplace texts?

No. Marketplace sections, services and partners have their own text file per language, imported under Marketplace. The import on the Languages page only replaces the general interface texts.

Setup

Which language codes can I use?

Use two-letter lower-case codes such as de, fr or pl. The add dialog also accepts three-letter and regional codes. The CSV import refuses any column header that is not exactly two letters, so such a language never receives texts.

Why does my new language show English everywhere?

A language added under Languages has no texts until a CSV file with its column is imported. Until then every key shows in English. The dash in the updated date column shows this state.

Why is the add button in the dialog disabled?

It stays disabled until the code matches the format. That is two or three lower-case letters, optionally a dash and two upper-case letters. The field shows Use ISO code like 'en', 'de', or 'en-US'. when the format is wrong.

What does the CSV header need to look like?

The first column can have any title, for example key. Every following column title must be a two-letter language code such as en, de or pl. Upper case is accepted and turned into lower case during the import.

The import

I imported ten corrected keys and now many texts are English. Why?

An import replaces each language’s whole file with the keys in the CSV. Keys not in your file were removed from those languages and now fall back to English. Import the complete set of texts, including the keys you did not change.

The import said success but my language did not change. Why?

The language’s code had not been added before the import, so its column was skipped. The import still reports success in that case. Add the language under Languages, then import the file again.

Why does the import refuse my file with Invalid language code in header?

A header cell after the first column is not a two-letter code. Examples are en-US, pl_PL, Polish or an empty title. Correct the header row and choose the file again. Nothing from the refused file was published.

Can a text contain commas or quotes?

Yes. Put the whole value in double quotes when it contains a comma. Write a quote inside it as two quotes. Line breaks inside a value are not supported, because the file is read line by line.

How large may the file be?

Up to 50 MB, as the rules in the dialog Update translations state. A typical file with all comrce Hub texts in a few languages is far below that.

When do users see the new texts?

Users see imported texts after their next page load in comrce Hub. A browser that stays open keeps the texts it loaded until the page is reloaded.

Languages in Settings

Why does a language appear in Settings before we imported it?

The language selector lists every language that exists under Languages, imported or not. Users who choose it see English until the import. Add a language only when its texts are ready.

Is a user’s language choice saved?

Yes. Choosing a language in the Settings selector switches the interface at once and saves the choice for the account. It applies at the next sign-in too. A language code that does not exist is refused.

What happens to users whose language is deleted?

They see English from their next page load, and the deleted language no longer appears in their selector. They can choose another language under Settings at any time.

Deleting

Can I undo deleting a language?

No. Deleting removes the language and its published files at once. Add the language again and import a CSV file with its column to restore it. Texts that were only in the deleted file are lost.

Can I delete English?

The page allows it, but you must not. English is the base every other language is built on. Without it comrce Hub cannot serve texts in any language, so keep the en row at all times.

Data and audit

Where do I see who imported translations?

Under Logs, the event Translations imported records who imported. It also names the file and which language codes were and were not updated.

Can I download the current texts of a language?

Each imported language has an arrow at the end of its row in the list under Languages. It opens the published text file in a new browser tab, where you can save it.

Troubleshooting

Symptom	What to check
Invalid language code in header.	Every header after the first column must be a two-letter code.
No language columns detected. or CSV must have at least two columns: key and at least one language column.	The header line has only one column. Check that the separator is a comma.
Selected file must be a CSV (.csv).	Save the file as CSV with the .csv extension.
A red message with a technical text such as “Request failed with status code 400”	Read the red line in the dialog for the actual reason.
Success, but a language’s updated date did not change	The language was not added before the import. Add it and import again.
Many texts suddenly in English	The CSV lacked keys. Import the complete set.
Texts in all languages show raw keys	Check that the en row exists and has an updated date.
A new language shows a raw key as its display name	comrce Hub has no translated name for that code. Prefer common two-letter codes.
Language code already exists.	The language exists. Import into it instead.
Users do not see new texts	They need to reload the page.

Still stuck?

Send the CSV file, the time of the import and the language codes to the comrce Hub developers. They can check the log entry and the published files.

Related

• The Languages page
• Languages overview
• Settings for staff