Simply localize your app with translations stored in Google Spreadsheet.

1. Add ACKLocalization to your Podfile

pod 'ACKLocalization`

2. Install pods

pod install

Just download binary from Github release

You can use ACKLocalization in two ways:

1. safer and recommended use with Service Account
2. use with API key

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.

You need to have a Google project in Google Dev console, there you go to Credentials ➡️ create credentials ➡️ service account key. Then you need to enable Google Sheets API in the console.

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

You need to have a Google project in Google Dev console, there you go to Credentials ➡️ create credentials ➡️ API Key. This will create unrestricted API key, we recommend to restrict it as much as possible - application restrictions are unluckily not possible to use - maybe if you intend to run the script on CI, then you can restrict it to certain IPs. What you can do is to restrict the API key to Google Sheets API (you might need to enable this API first in the console).

You get the spreadsheet identifier from its URL:

https://docs.google.com/spreadsheets/d/<YOUR_SPREADSHEET_ID>/edit#gid=0

The file is named localization.json. This is how example file looks like, you can find the Swift representation here:

{
    "defaultFileName": "Localizable",
    "destinations": {
        "Localizable": "Framework/Resources",
        "InfoPlist": "App/Resources"
    },
    "keyColumnName": "iOS",
    "languageMapping": {
        "CZ": "cs"
    },
    "serviceAccount": "Resources/ServiceAccount.json",
    "spreadsheetID": "<GOOGLE_SPREADSHEET_ID>",
}

Attributes documentation:

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.

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.

Just call the binary, remember that the configuration file has to be in the same directory where you call ACKLocalization.

Pods/ACKLocalization/Localization

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.

This is example folder structure of the project

|-localization.json
|-Podfile
|-Project.xcodeproj
|-ServiceAccount.json
|-App
|---Resources
|------en.lproj
|----------InfoPlist.strings
|------cs.lproj
|----------InfoPlist.strings
|-Framework
|---Resources
|------en.lproj
|----------Localizable.strings
|----------Localizable.stringsDict
|------cs.lproj
|----------Localizable.strings
|----------Localizable.stringsDict

This is example structure of the spreadsheet with translations

This is the example config file:

{
    "defaultFileName": "Localizable",
    "destinations": {
        "Localizable": "Framework/Resources",
        "InfoPlist": "App/Resources"
    },
    "keyColumnName": "key_ios",
    "languageMapping": {
        "CS": "cs",
        "EN": "en"
    },
    "serviceAccount": "Resources/ServiceAccount.json",
    "spreadsheetID": "<GOOGLE_SPREADSHEET_ID>",
    "spreadsheetTabName": "Localizations"
}

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.";

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:

Ackee team

ACKLocalization is available under the MIT license. See the LICENSE file for more info.