ACKLocalization
Simply localize your app with translations stored in Google Spreadsheet.
Installation
Cocoapods
- Add ACKLocalization to your Podfile
pod 'ACKLocalization`
- Install pods
pod install
Manually
Just download binary from Github release
Usage
You can use ACKLocalization in two ways:
- safer and recommended use with Service Account
- use with API key
Use with Service Account
This method is safe in the way that you can fully control who has access to your spreadsheet. You create a service account, invite it as viewer to your spreadsheet and you're ready to go.
Create a Service Account
You need to have a Google project in Google Dev console, there you go to Credentials
Invite Service Account to your spreadsheet
The Service Account has associated email address, you need to invited that address to your spreadsheet, so it is available to read the document.
Now you can skip to getting your spreadsheet identifier
Use with API key
You need to have a Google project in Google Dev console, there you go to Credentials
Get your Google Spreadsheet identifier
You get the spreadsheet identifier from its URL:
https://docs.google.com/spreadsheets/d/<YOUR_SPREADSHEET_ID>/edit#gid=0
Now you can build your configuration file
The file is named localization.json
. This is how example file looks like, you can find the Swift representation here:
{
"destinationDir": "Resources",
"keyColumnName": "iOS",
"languageMapping": {
"CZ": "cs"
},
"serviceAccount": "Resources/ServiceAccount.json",
"spreadsheetID": "<GOOGLE_SPREADSHEET_ID>",
"stringsFileName": "Localizable.strings",
"spreadsheetTabName": "Localizations"
}
Attributes documentation:
Name | Required | Note |
---|---|---|
destinationDir |
Path to destination directory where generated strings files should be saved | |
keyColumnName |
Name of column that contains keys to be localized | |
languageMapping |
Mapping of language column names to app languages, you specify how columns in spreasheet should be mapped to app languages | |
apiKey |
API key that will be used to communicate with Google Sheets API, apiKey or serviceAccount has to be provided |
|
serviceAccount |
Path to service account file that will be used to access spreadsheet, apiKey or serviceAccount has to be provided |
|
spreadsheetID |
Identifier of spreadsheet that should be downloaded | |
spreadsheetTabName |
Name of spreadsheet tab to be fetched, if nothing is specified, we will use the first tab in spreadsheet | |
stringsFileName |
Name of strings file that should be generated |
The file has to be in the same directory where you call ACKLocalization.
To be able to communicate with Google Sheets API, you need to provide either apiKey
or serviceAccount
parameter or use environment variable. If both are provided, then serviceAccount
will be used.
Environment variables
Do you want to share secrets across multiple projects, or do you not want to keep secrets in the project repository? We have the solution for you. Just set one of the environment variables below.
ACKLOCALIZATION_SERVICE_ACCOUNT_PATH
- Path to service account file that will be used to access spreadsheet
ACKLOCALIZATION_API_KEY
- API key that will be used to communicate with Google Sheets API
apiKey
or serviceAccount
defined in localization.json
have higher priority than environment values.
If both are provided then ACKLOCALIZATION_SERVICE_ACCOUNT_PATH
will be used.
Calling ACKLocalization
Just call the binary, remember that the configuration file has to be in the same directory where you call ACKLocalization.
Pods/ACKLocalization/Localization
Example
We love to call ACKLocalization from Xcode (we have a separate aggregate target which calls the script) so I'll stick with that with this example.
Project structure
This is example folder structure of the project
|-localization.json
|-Podfile
|-Project.xcodeproj
|-Project
|---Resources
|------ServiceAccount.json
|------en.lproj
|----------Localizable.strings
|----------Localizable.stringsDict
|------cs.lproj
|----------Localizable.strings
|----------Localizable.stringsDict
Spreadsheet structure
This is example structure of the spreadsheet with translations
key_ios | EN | CS |
---|---|---|
hello | Hello | Ahoj |
Example config file for this case would be
This is the example config file:
{
"destinationDir": "Resources",
"keyColumnName": "key_ios",
"languageMapping": {
"CS": "cs",
"EN": "en"
},
"serviceAccount": "Resources/ServiceAccount.json",
"spreadsheetID": "<GOOGLE_SPREADSHEET_ID>",
"stringsFileName": "Localizable.strings",
"spreadsheetTabName": "Localizations"
}
Plist keys
ACKLocalization supports localizing plist files. Simply prefix the key with plist.InfoPlist
, where InfoPlist
is the name of plist you need to localize and ACKLocalization will automatically generate respective InfoPlist.strings
files. Please note that InfoPlist
name is case-sensitive.
Example keys:
plist.InfoPlist.NSPhotoLibraryAddUsageDescription
plist.InfoPlist.NSUserTrackingUsageDescription
InfoPlist.strings
result:
"NSPhotoLibraryAddUsageDescription" = "Your photo library usage message.";
"NSUserTrackingUsageDescription" = "Your tracking permission message.";
Plural keys
To add plurals to the spreadsheet, you need to specify the translation key and the plural type using the following native convention:
translation.key##{zero}
translation.key##{one}
translation.key##{two}
translation.key##{few}
translation.key##{many}
translation.key##{other}
This will be automatically generated into Localizable.stringsDict
and the key won't be presented in Localizable.strings
.
Example:
Author
Ackee team
License
ACKLocalization is available under the MIT license. See the LICENSE file for more info.