Supported formats
      Back to home
      1. Help Center
      2. Supported formats

      CSV

      Everything you need to know about handling CSV localization files in Phrase.

      File Extensions   .csv
      API Extension            csv
      Import     Yes
      Export   Yes
      Pluralization supported?     Yes
      Descriptions supported?   Yes
      Format Options key_index, comment_index, tag_column column_separator, quote_char, header_content_row, enable_pluralization, export_tags, export_max_characters_allowed


      CSV, short for “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 (hence the name of the file format). 

      Phrase can help you to streamline the management of CSV files for localization purposes.  Before import, you need to make sure that the CSVs you are about to localize have three fields for a single line, representing source content, translation, and comments (optional), respectively.

      Params

      Locale mapping 

      Indentifier locale_mapping  
      Type hash
      Upload Yes      
      Download No            
      Default [optional]
      Description Hash mapping each locale name to the column index it is contained in. Column indices start at 1

      Format Options 

      Key Index

      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.

      Comment Index 

      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 .

      Tag column

      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 .

      Column separator 

      Identifier column_separator  
      Type string  
      Upload Yes      
      Download No
      Default ,
      Description Char that is used to separate columns.

      Quote char

      Identifier quote_char
      Type string
      Upload Yes
      Download No
      Default "
      Description Char that is used to quote newlines and column separator.

      Header content row 

      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.


      Enable pluralization 

      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.

      Export tags

      Identifier export_tags
      Type boolean
      Upload No    
      Download Yes    
      Default false 
      Description Exports tags along with keys and translations.

      Export max characters

      Identifier export_max_characters_allowed
      Type boolean
      Upload No    
      Download Yes    
      Default false 
      Description Exports the key character limit along with keys and translations.

      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 should be structured like this:

      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 in your .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

      Pluralization

      This format uses named categories to identify the different pluralizations of a key. The following categories are reserved for pluralization:

      .zero | .one | .two | .few | .many | .other

      Example key names:
      inbox.messages.notification.one
      inbox.messages.notification.other

      This way pluralized keys can be identified, persisted and marked accordingly.
      Learn more about pluralization?