ADLocalize is a simple way to manage your localization files. Supported wording sources : CSVs and Google Sheets. Localization file generation available for iOS, Android, JSON (i18next), YAML and Java properties
The purpose of this gem is to automatically generate wording files from a CSV input (CSV file or Google Spreadsheet).
It supports iOS, Android, JSON, YAML and Java Properties.
It is a useful tool when working on a mobile application or a SPA.
When using the CLI replace GCLOUD_CLIENT_SECRET=$(cat <path-to-client-secret.json>)
with GOOGLE_APPLICATION_CREDENTIALS=<path-to-client-secret.json>
When using the interactor refer to ruby program usage section
Add this line to your application’s Gemfile:
gem 'ad_localize'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install ad_localize
$ ad_localize -h
https://docs.google.com/spreadsheets/d/<your-spreadsheet-drive-key>/edit#gid=<sheet-id>
.$ ad_localize -k <your-spreadsheet-drive-key>
$ ad_localize -k <your-spreadsheet-drive-key> -s <comma-separated-sheet-id-list>
$ GOOGLE_APPLICATION_CREDENTIALS=<path-to-client-secret.json> ad_localize -k <your-spreadsheet-drive-key>
$ GOOGLE_APPLICATION_CREDENTIALS=<path-to-client-secret.json> ad_localize -k <your-spreadsheet-drive-key> -e
$ ad_localize -o ios
$ ad_localize -t <path-to-the-output-directory>
$ ad_localize -d
$ ad_localize -x
$ ad_localize --auto-escape-percent
$ ad_localize -l fr,en
$ ad_localize --skip-value-stripping
There are many possibilities when using AdLocalize in a ruby program. You can add support to your own wording format, support other platforms, select which locales you want to export, generate wording file content without writing on the disk and many more.
Here is an example of how to use it to produce the same output as the command line.
If you want more examples, please open a documentation issue.
require 'ad_localize'
# create export request
export_request = Requests::ExportRequest.new
export_request.spreadsheet_id = 'some_id'
export_request.sheet_ids = %w[first second]
export_request.verbose = true
begin
# download files - be sure that GOOGLE_APPLICATION_CREDENTIALS is set if you use service account
export_request.downloaded_csvs = AdLocalize::Interactors::DownloadSpreadsheets.new.call(export_request: export_request)
# execute request
AdLocalize::Interactors::ProcessExportRequest.new.call(export_request: export_request)
ensure
export_request.downloaded_csvs.each do |file|
file.close
file.unlink
end
end
If you do not have high security concerns, the simplest way to access a google spreadsheet is to allow anyone with the link to view it and enable the Viewers and commenters can see the option to download, print, and copy
option in the spreadsheet sharing settings.
To use a private google spreasheet you need to use a Google Cloud Service Account. Here are the steps to follow :
client-secret.json
(in a password manager for example)$ GOOGLE_APPLICATION_CREDENTIALS=<path-to-client-secrets> ad_localize -k # one way
$ GOOGLE_APPLICATION_CREDENTIALS=<path-to-client-secrets> ad_localize -k <your-spreadsheet-drive-key> -s <comma-separated-sheet-id-list> # another way
$ export GOOGLE_APPLICATION_CREDENTIALS=<path-to-client-secrets>
$ ad_localize -k <your-spreadsheet-drive-key> # one way
$ ad_localize -k <your-spreadsheet-drive-key> -s <comma-separated-sheet-id-list> # another way
key | fr | en |
---|---|---|
# General | ||
agenda | agenda | events |
favorites | Mes favoris | My favorites |
from_to | du %1$@ au %2$@ | from %1$@ to %2$@ |
key
column will be considered as a locale column (except from the optional comment
columns)"%1$@ %2$@'s report"
).Only for Android and iOS
To add comments for iOS or Android, simply add a comment column using the naming convention comment <locale>
.
Comments are available in strings.xml
, Localizable.strings
, Localizable.stringsdict
, InfoPlist.strings
. Here is an example for InfoPlist.strings
:
key | en | comment en |
---|---|---|
player_time_live | Live | bypass-unused-error |
seconds | seconds | bypass-untranslated-error |
"player_time_live" = "Live"; // bypass-unused-error
"seconds" = "seconds"; // bypass-untranslated-error
Only for Android and iOS
Syntax for plural keys in the CSV file: key##{text}
.
key | fr |
---|---|
assess_rate_trip_voiceover##{one} | Rate %1$@ star |
assess_rate_trip_voiceover##{other} | Rate %1$@ stars |
Only for Android
If you want to share a spreadsheet between iOS and Android, you can write the wording using the iOS string interpolation convention.
The translation to android convention will be done automagically.
Only for iOS
Syntax for adaptive keys in the CSV file: key##{number}
.
key | fr |
---|---|
start_countdown##{20} | Start |
start_countdown##{25} | Start countdown |
start_countdown##{50} | Start countdown |
Only for iOS.
Every key that matches the following formats will be added to the InfoPlist.strings
file instead of Localizable.strings
:
NS...UsageDescription
NFCReaderUsageDescription
CF...Name
Only for YAML and JSON
For these two platforms it is common to have nested wording files, either to handle plural or to group wording by sections. To handle this behavior in a simple way you should use dots in the key to separate the different levels. For example :
key | fr |
---|---|
login.password | mot de passe |
login.email |
{"login":{"password":"mot de passe","email":"email"}}
fr:
login:
password: "mot de passe"
email: "email"
The default output folder name is exports
.
If your export is for multiple platforms there will be an intermediate folder for each platform, otherwise the wording files (and folders) will directly be generated in the export folder.
Any existing file will be overriden.
You can see examples of generated files in test/fixtures/export_references/
Here an export tree example for all supported platforms in fr
and en
:
exports/
├── android
│ ├── values
│ │ └── strings.xml
│ └── values-en
│ └── strings.xml
├── ios
│ ├── en.lproj
│ │ ├── InfoPlist.strings
│ │ ├── Localizable.strings
│ │ └── Localizable.stringsdict
│ └── fr.lproj
│ ├── InfoPlist.strings
│ ├── Localizable.strings
│ └── Localizable.stringsdict
├── json
│ ├── en.json
│ └── fr.json
├── properties
│ ├── en.properties
│ └── fr.properties
└── yml
├── en.yml
└── fr.yml
After checking out the repo, run bin/setup
to install dependencies. Then, run rake test
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
To see all available commands run bundle exec rake -T
.
Bug reports and pull requests are welcome on GitHub at https://github.com/applidium/ad_localize. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
release
branchlib/ad_localize/version.rb
make publish
You may need to configure your account at step 4.
if you’ve never pushed any gem. You can find all the informations you need on the official documentation.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the AdLocalize project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.