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
- Display help
$ ad_localize -h
- Export wording from a public google spreadsheet, default tab. The spreadsheet key and sheet_id are available in the spreadsheet url. For example
https://docs.google.com/spreadsheets/d/<your-spreadsheet-drive-key>/edit#gid=<sheet-id>
.
$ ad_localize -k <your-spreadsheet-drive-key>
- Export wording from a set of google spreadsheet tabs.
$ ad_localize -k <your-spreadsheet-drive-key> -s <comma-separated-sheet-id-list>
- Export wording from a private google spreadsheet. It requires a Google Cloud Service Account.
$ GOOGLE_APPLICATION_CREDENTIALS=<path-to-client-secret.json> ad_localize -k <your-spreadsheet-drive-key>
- Export wording from all sheets in a google spreadsheet. It requires a Google Cloud Service Account.
$ GOOGLE_APPLICATION_CREDENTIALS=<path-to-client-secret.json> ad_localize -k <your-spreadsheet-drive-key> -e
- Only generate wording files for the specified platforms
$ ad_localize -o ios
- Choose the path of the output directory
$ ad_localize -t <path-to-the-output-directory>
- Run in debug mode. In this mode, logs are more verbose
$ ad_localize -d
- Won't generate keys with empty values (iOS feature only, automatically handled for Android)
$ ad_localize -x
- Will escape % character present in wordings (iOS feature only), this is useful when using the wording through String(format:)
$ ad_localize --auto-escape-percent
- Only generate wording files for the specified locales
$ ad_localize -l fr,en
- Keep extra spaces before and after translated values
$ 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 = DownloadSpreadsheets.new.call(export_request: export_request)
# execute request
AdLocalize::Interactors::ExecuteExportRequest.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 :
- Create a GCloud Service Account:
- Go to Google Cloud Console
- Either create a new project or use an existing one (when using Firebase, a GCloud project is created)
- Go to IAM & Admin / Service Account and create a new service account.
- Store the created
client-secret.json
(in a password manager for example)
- Enable Google Spreadsheet API for the project
- Go to API / Library and enable the Google Spreadsheet API there.
- Add the service account to a spreadsheet.
- In IAM & Admin / Service Account, the service account's email is listed. Invite it to the spreadsheet to export.
$ 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$@ |
- Any column after the
key
column will be considered as a locale column (except from the optionalcomment
columns) - Keys should contain only letter, number, underscore and dot : [a-z0-9_.]+.
- Format specifiers must be numeroted if there are more than one in a translation string (eg:
"%1$@ %2$@'s report"
). - Only for Android keys without translation won't be considered
- Lines starting with a comment will be ignored
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.
- After all your changes are reviewed and merged
- Create a
release
branch - Update the version in
lib/ad_localize/version.rb
- Execute
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.