> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolk.every-day.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Importing

> Read in existing language files, with a preview first.

An import brings existing translations into Tolk, for example when you connect a project or when a translation agency sends a file back. Tolk always shows a preview first and only writes after you confirm. Managers and developers can import.

## Supported formats

| Format | Example path |
| - | - |
| Laravel PHP | `lang/de/auth.php` |
| Laravel JSON | `lang/de.json` |
| JSON for JS (flat or nested) | `resources/js/lang/de.json` |
| PO and MO (gettext), POT | `languages/everyday-i18n-de_DE.po` |
| WordPress PHP | `languages/de_DE.l10n.php` |
| CSV and XLSX | `translations.xlsx` |
| XLIFF 1.2 and 2.0 | `de.xliff` |
| Zip with a whole `lang/` or `languages/` folder | `lang.zip` |

Tolk recognizes the format, the language and the namespace from the path: `lang/de/auth.php` becomes language `de`, namespace `auth`. If Tolk cannot derive the language, you choose it yourself.

## How to import

<Steps>
  <Step title="Choose files">
    In the editor, click **Import** (*Importeren*) and drag one or more files or a zip into the window. You can upload up to 20 files at once.
  </Step>

  <Step title="Map columns (CSV and XLSX)">
    For each column, say what it contains: exactly one column with the key and a column per language you want to import. Optional: namespace, context, plural and description. Tolk ignores columns you do not map. Without a language column, the file only creates keys; see [Importing keys only](#importing-keys-only).

    * The mapping works on the **position** of the column, so two columns with the same heading or an empty heading can still be mapped separately.
    * A column without a heading but with values is called "Column C" (*Kolom C*; the letter as in Excel). Tolk leaves out a column with neither a heading nor values.
    * With **Save as preset** (*Bewaren als preset*), Tolk uses the same layout automatically next time, for a file with the same headings in the same order. Useful when a customer always delivers the same Excel file.
    * Tolk suggests a mapping from the headings: `key`, `namespace`, `context`, `plural` and `description` name their role, and a language code or name (`de`, `de_DE`, `German`, `Duits`) names a language. A file with one other column besides those, such as `key,value`, gets the language of the editor you imported from for that column.
    * Under the table, Tolk says why the mapping cannot be applied yet: no key column or more than one, a language in two columns, or namespace, context, plural or description in two columns. **Apply columns** (*Kolommen toepassen*) is available as soon as the mapping is valid.
  </Step>

  <Step title="Review the preview">
    Tolk counts new translations, translations that change an existing one, unchanged lines, unknown keys and placeholder errors. With **Show examples** (*Voorbeelden bekijken*) you see a few lines of each kind.

    For a CSV or XLSX file, the preview shows the languages of your column mapping next to **Change columns** (*Kolommen aanpassen*); you change them there, not with a language field. For other files you choose the language in the preview. After a change, Tolk counts again while the preview stays in place and keeps your choices.

    If the new keys do not fit within the key limit of the [plan](/guide/plan-and-usage), the preview says how much room is left and you cannot import with **Create unknown keys** (*Onbekende keys aanmaken*) switched on. Switch that option off to update existing keys only, or contact Every Day for a larger plan.
  </Step>

  <Step title="Choose options">
    * **Overwrite existing translations** (*Bestaande vertalingen overschrijven*): when off, Tolk only fills empty translations; when on, it also replaces existing ones.
    * **Create unknown keys**: keys that are not yet in the project are created.
    * **Add a tag to new keys** (*Tag toevoegen aan nieuwe keys*, optional).
  </Step>

  <Step title="Import">
    Click **Import … translations** (*… vertalingen importeren*). The import continues in the background, even if you close the window. You get a notification when it is done.
  </Step>
</Steps>

## Importing keys only

A CSV or XLSX file with a key column but no language column creates keys without translations, for example a list of new keys from a developer with their descriptions. Map the key column and, optionally, the namespace, context, plural and description; under the table Tolk confirms that only keys will be created.

* The preview counts **New keys** (*Nieuwe keys*), keys that **Already exist** (*Bestaan al*) and **Archived** (*Gearchiveerd*) keys, and shows **Keys only** (*Alleen keys*) instead of the languages. The button reads **Import … keys** (*… keys importeren*).
* New keys are always created, with their namespace, context, description and, when the plural column names categories such as `one` and `other`, as a plural key. You can add a tag to them.
* Existing keys stay as they are, also their description. To change descriptions, import them together with the source language.
* Archived keys are skipped. A key that appears twice in the file is an error of the file.
* You need the right to create keys, and the new keys must fit within the key limit of the [plan](/guide/plan-and-usage). Each key counts as one line toward the 50,000 lines per import.
* A file without a language column cannot be imported together with translation files: import it separately.
* A column mapping without a language can be saved as a preset, like any other.

Keys that are their own text, such as the keys of a Laravel JSON file, can then be copied into their translations in the editor with **Use key as translation** (*Key overnemen als vertaling*); see [Using the key as the translation](/guide/editor#using-the-key-as-the-translation).

## How large an import may be

| Limit | Maximum |
| - | - |
| Lines per import (keys × languages, all files together) | 50,000 |
| Rows per spreadsheet | 50,000 |
| Files per upload | 20 |
| Size per file / per upload | 50 MB / 100 MB |

A project with 10,000 keys in 5 languages fits exactly. If the import is larger, Tolk says: "This import is too large: at most 50,000 lines (keys × languages) per import. Split the files and import them in parts." In that case, split by language or by namespace.

## What Tolk skips

* Archived keys.
* Empty lines.
* Lines that do not fit the key, such as plural forms for a key without plurals.

A translation with a placeholder error is imported. You fix it afterwards in the editor; until then it is not included in an export.

## Security

* PHP files are never executed. Tolk only reads arrays of strings; it rejects everything else.
* Zip files are checked for unsafe paths, symbolic links, encryption and suspiciously large content.

<Tip>
  You can also import through the API, for example from CI. See [Imports and exports through the API](/developers/imports-and-exports).
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.