Mobile Text Tools

Mobile Text Tools is a set of tools to export translations to Android and IOS mobile applications. It provides a data model represented in json and can read and write different formats.

Features

• import .csv, .xls, .xlsx, .json
• export .csv, .json, android resources, ios resoures
• custom rows format import and export
• string escape
• token replacement: you must use the {} or {1}..{n} notation in source files

CLI

$ update_wordings --help
usage: update_wordings [-h] [-o [OUT_FILE [OUT_FILE ...]]]
                          [-a ANDROID_RES_DIR] [-i IOS_RES_DIR]
                          [--android-resname ANDROID_RESNAME]
                          [--ios-resname IOS_RESNAME] [-s] [-f FORMAT_CONFIG]
                          input_file

Export wordings for Android & IOS.

positional arguments:
  input_file            .csv, .xls, .xlsx, .json formats are supported.

optional arguments:
  -h, --help            show this help message and exit
  -o [OUT_FILE [OUT_FILE ...]], --out-file [OUT_FILE [OUT_FILE ...]]
                        .json or .csv output file path (default: [])
  -a ANDROID_RES_DIR, --android_res_dir ANDROID_RES_DIR
                        resource directory for android strings (default: None)
  -i IOS_RES_DIR, --ios_res_dir IOS_RES_DIR
                        resource directory for ios strings (default: None)
  --android-resname ANDROID_RESNAME
                        filename for android resource (default: strings.xml)
  --ios-resname IOS_RESNAME
                        filename for ios resource (default: i18n.strings)
  -s, --split-files     Export sections as separate ios and android resource
                        files, comment key is used for naming new files
                        (default: False)
  -f FORMAT_CONFIG, --format-config FORMAT_CONFIG
                        excel and csv format specifications config file
                        (default: None)

Default csv and xls format specification configuration :

{
  "excel_sheet_reference": 0,
  "key_col": 0,
  "exportable_col": 1,
  "is_comment_col": 2,
  "comment_col": 3,
  "translations_start_col": 4,
  "exportable_value": null,
  "is_comment_value": null,
  "metadata_cols": {}
}

• excel_sheet_reference: is the worksheet number (int) or name (string) for excel import
• exportable_value: is the value to match in exportable_col to tell if the value will be exported to Android or IOS, can be a string or a list of strings, null will match True for any non empty value in the column.
• is_comment_value: same as exportable_value to tell if the line is a comment

Example csv or xls table with default format :

key	exportable	is_comment	comment	en	fr	de
Menu	Yes	Yes	Menu Screen
menu.welcome	Yes			Welcome	Bienvenue	Willkommen
menu.contact	Yes			Contact	Contact	Kontakt
Share	Yes	Yes	Share Screen
share.share	Yes			Share	Partager	Teilen

To generate translations for android and ios from .xlsx file :

$ update_wordings my_wordings.xlsx -i out/ios -a out/android

To generate translations from json file for android with custom resource filename :

$ update_wordings my_wordings.json -a out/android --android-resname my_strings.xml

Python interface

import mobileStrings

Read :

Function read_file(f) from module text_in supports .xls, .xlsx, .csv, .json file formats.

languages, wordings = mobileStrings.text_in.read_file('./test_translations.json')
print ', '.join(languages)

en, fr, de, pt, it, es, nl, zh, ja, pl, pt_BR, ru, id, ko, ar, tr, th, sv

Read custom formats :

For formats represented as rows like .csv and .xls, you can specify columns numbers with FormatSpec

specs = mobileStrings.text_in.FormatSpec(0, 1, 2, 3, 4, bool, bool, {}) # Default format_spec (all params are optional)

languages, wordings = mobileStrings.text_in.read_file('./test_translations.csv', specs)
print ', '.join(languages)

en, fr, de, pt, it, es, nl, zh, ja, pl, pt_BR, ru, id, ko, ar, tr, th, sv

Query :

To search a wording by its key, you can convert the list of Wording to a dict

# wordings is a list, create a dict to query
d = dict((w.key,w) for w in wordings)
print('# keys: ')
print '\n'.join(d.keys())

welcome_wording = d.get('menu.welcome')

print('\n# ' +welcome_wording.comment+':')
print welcome_wording.translations.get('fr')
print welcome_wording.translations.get('de')

# keys:
menu.home
menu.contact
menu.share
menu.welcome
menu.news
menu.share.not.exported
menu.infos
comment.generated
comment.section

# Title on menu header:
Bienvenue !
Willkommen!

Write :

Writing is very simple : use a write_ function from the text_out module. It supports Android, IOS, json, csv output formats.

For mobile applications :

mobileStrings.text_out.write_android_strings(languages, wordings, '~/dev/myAndProject/res')
mobileStrings.text_out.write_ios_strings(languages, wordings, '~/dev/myIOSProject/res')

Csv example :

import cStringIO
sf = cStringIO.StringIO()

# Write csv in a file-like object, for the first 3 languages only
mobileStrings.text_out.write_csv(languages[:3], wordings, sf)
print sf.getvalue()
sf.close()

key,exportable,is_comment,comment,en,fr,de
comment.generated,Yes,Yes,Generated by mobile dev tools - Do not modify,,,
menu.welcome,Yes,,Title on menu header,Welcome!,Bienvenue !,Willkommen!
menu.home,Yes,,Home item,Home,Accueil,Start
menu.news,Yes,,News item,News,Actualités,News
comment.section,Yes,Yes,This is a section,,,
menu.contact,Yes,,Contact item,Contact,Contact,Kontakt
menu.infos,Yes,,Information pages item,Info,Infos,Informationen
menu.share.not.exported,,,Share application item - not exported,Share,Partager,Teilen
menu.share,Yes,,Share application item,Share,Partager,Teilen
menu.share,Yes,,Share application item,,Partager,Teilen