File Extensions |
.csv |
API Extension |
csv |
Import |
Yes |
Export |
Yes |
Plural forms support |
Yes |
Description support |
Yes |
Format options |
key_index comment_index tag_column max_characters_allowed_column column_separator quote_char header_content_row enable_pluralization export_tags export_max_characters_allowed custom_metadata_columns export_key_id key_id_column |
CSV (comma-separated values) is a popular file format used primarily for data transfer in various applications and programs. In a CSV file, each line is a data record. Each record consists of a few fields separated by commas. Before import, ensure that the CSV files have three fields for a single line representing source content, translation, and comments (optional).
The locale_mapping
parameter (of type hashmap) is required to specify which column in the document corresponds to each locale. For examples, see the configuration file example and the API documentation for uploads.
Format Options
Identifier |
key_index |
Type |
integer |
Upload |
Yes |
Download |
No |
Default |
[empty] |
Description |
Index of the column containing the key names. Column indexes start at 1. |
Identifier |
comment_index |
Type |
integer |
Upload |
Yes |
Download |
No |
Default |
[empty] |
Description |
Index of the column containing description for the key. Column indexes start at 1. |
Identifier |
tag_column |
Type |
integer |
Upload |
Yes |
Download |
No |
Default |
[empty] |
Description |
Index of the column containing a tag for the key. Column indexes start at 1. |
Identifier |
max_characters_allowed_column |
Type |
integer |
Upload |
Yes |
Download |
No |
Default |
[empty] |
Description |
Index of the column containing a maximum number of characters for the key. Column indexes start at 1. |
Identifier |
column_separator |
Type |
string |
Upload |
Yes |
Download |
No |
Default |
, |
Description |
Char that is used to separate columns. |
Identifier |
quote_char |
Type |
string |
Upload |
Yes |
Download |
No |
Default |
" |
Description |
Char that is used to quote newlines and column separator. |
Identifier |
header_content_row |
Type |
boolean |
Upload |
Yes |
Download |
No |
Default |
false |
Description |
Indicates whether the first row contains only header information and should be skipped. |
Identifier |
enable_pluralization |
Type |
boolean |
Upload |
Yes |
Download |
No |
Default |
true |
Description |
Enables detection of pluralized keys. All matching keys will be persisted as pluralized keys. |
Identifier |
export_tags |
Type |
boolean |
Upload |
No |
Download |
Yes |
Default |
false |
Description |
Exports tags along with keys and translations. |
Identifier |
export_max_characters_allowed |
Type |
boolean |
Upload |
No |
Download |
Yes |
Default |
false |
Description |
Exports the key character limit along with keys and translations. |
Identifier |
custom_metadata_columns |
Type |
hash |
Upload |
Yes |
Download |
Yes |
Default |
[empty] |
Description |
HashMap of custom metadata values that need to be imported or exported:
|
Identifier |
export_key_id |
Type |
boolean |
Upload |
No |
Download |
Yes |
Default |
false |
Description |
Exports the key character limit along with keys and translations. |
Identifier |
key_id_column |
Type |
integer |
Upload |
No |
Download |
Yes |
Default |
[empty] |
Description |
Index of the column containing the ID for the key. Column indexes start at 1. |
Code sample
boolean_key,"--- true " empty_string_translation,"" key_with_description,Check it out! This key has a description! (At least in some formats),This is the amazing description for this key! key_with_line-break,"This translations contains a line-break." nested.deeply.key,"Wow, this key is nested even deeper." nested.key,This key is nested inside a namespace. null_translation, pluralized_key.one, "Only one kitten found." pluralized_key.other,"Wow, you have %s kittens!" pluralized_key.zero,"You have no kittens." sample_collection,"--- - first item - second item - third item " simple_key,Just a simple key with a simple message. unverified_key,This translation is not yet verified and waits for it. (In some formats we also export this status)
File structure
A typical .CSV file structure:
1 (Key column), 2 (Translation column), 3 (Comment column) app_title, My Software Project, This is the main title apples.zero, one apple, my comment ...
Configuration example
An example for the push section of a .phrase.yml for .CSV files:
push: sources: - file: "./multi.csv" params: update_translations: true locale_mapping: en: 2 de: 3 format_options: comment_index: 4 tag_column: 5
This format uses named categories to identify the different pluralizations of a key. The following categories are reserved for plural forms:
.zero | .one | .two | .few | .many | .other
Example names for correctly identified, persisted and marked pluralized keys:
-
inbox.messages.notification.one
-
inbox.messages.notification.other
Files should follow this structure:
1 (Key column), 2 (Translation column), 3 (Comment column) messages.zero, No messages received, messages.one, One message received, messages.other, %s messages received,