ad_localize 3.6.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 736260ad38d18773bf3b8ed6441534bb3467f49edeae2335c7ec5b8742f934e9
-  data.tar.gz: 38cb4f5d8647cc997dc2eb0c784b42469ae5dbb51aad9ba8f19f97907654a181
+  metadata.gz: 1581d41a8d5a3f41dc91cf69f4b8abfdf8c2121695cf116a46c738825818cbd9
+  data.tar.gz: 64af1cc80f9e9247514c334e13f6252e267283e3c38ade2d3111a4deb252164b
 SHA512:
-  metadata.gz: 5448a25049abad18258c563bd84809a3f38cfefa54a60ace5c80fd7f214af81dcb30effb3a1d907962e6fb7d5707de322159e7361ef80ae01925124914d1a9ac
-  data.tar.gz: a139d77e6c76386493c3cb8d7d39aaf2c3a9526cba30a05b9aff2adaaccf326cb71303919a888da7329b4d56bef72f51211b0ee7fd3aa21e1641e0156ea0461e
+  metadata.gz: 0ebfdd0a7746acdaa06b713c6f129b04b7a81fb0441bf5975a47b415b892dd135b87c3e99e0610a98584adb2317f4d170a64230f932db3a3c0c3ecf8d00eabee
+  data.tar.gz: bd9a7140d68dc5f76c6c9e0dc19342180083205079d6d4e6022c0039176ae36f9e8c50441dec84bd5ea89f6596812c998be246163c3a9942e5fd9661379c3c30

data/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.0] - 2020-10-19
+### Breaking change
+  - Precedence to csv files. Only CSV files will be exported if both csv file and google spreadsheet are provided
+  - In case of multiple CSVs or sheet ids, you should be aware that all sources will be merged. By default the merge policy to keep the first wording translation for each key
+  - New architecture. Separate export process responsibilities in dedicated classes. Fixes [#48](https://github.com/applidium/ad_localize/issues/48), [#20](https://github.com/applidium/ad_localize/issues/20)
+ 
+### Changed
+  - it is now possible to provide an output path path that does not exist
+  - if a service account configuration is provided, there won't be any files downloaded
+  - it is now possible to provide a sheet id list
+  - `ActiveSupport::TestCase` is now the base class of test classes
+  - Only global constants are in the constant class
+  - Replaced the Runner class file by a cli class
+  - tests for ad_localize class are restricted to the minimum
+  - No more file generated when there are no data to export
+  - Less verbose logs. Now, they only describe the different steps of the export process
+  - do not add `InfoPlist` translations to android `strings.xml` 
+  
+### Added
+  - -e, -export_all_sheets option export all sheets from a spreadsheet by [@sjcqs](https://github.com/sjcqs)
+  - -m, --merge-option to select the merge policy (`keep` or `replace`) by [@sjcqs](https://github.com/sjcqs)
+  - it is now possible to select which locales you want to export
+  - key class is tested
+  - option handler is tested
+  - execute_export_request is tested (only csv)
+  - export request is tested
+  - dedicated folder for fixture files
+  - add ability to use AdLocalize in a Ruby program
+  - add documentation for JSON and YAML support. Fixes [#23](https://github.com/applidium/ad_localize/issues/23)
+  
+### Fixed
+  - comments will now be added to iOS and Android plural files
+  - do not remove existing files in export output folder. Fixes [#40](https://github.com/applidium/ad_localize/issues/40)
+
+### Removed
+  - no more option -a option to indicate that a service account configuration will be provided. If set, the environment variable `GCLOUD_CLIENT_SECRET` content will be used
+  - no more substitution of empty wording with by "Missing Translation" when using the option -d
+  - no more Makefile, the Rakefile is sufficient. Use `bundle exec rake -T` to display the available commands
+  - no more check for ordered interpolation variables in translations 
+  
 ## [3.6.0] - 2020-06-23
 ### Added
   - add documentation for service account usage by [@sjcqs](https://github.com/sjcqs)
@@ -12,7 +52,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 ### Fixed
-  
+
 ## [3.5.0] - 2020-05-12
 ### Added
   - add support for private spreadsheet using google service acccount by [@sjcqs](https://github.com/sjcqs). Fixes [#31](https://github.com/applidium/ad_localize/issues/31)

data/Gemfile.lock

@@ -1,16 +1,18 @@
 PATH
   remote: .
   specs:
-    ad_localize (3.5.0)
+    ad_localize (4.0.0)
       activesupport (>= 5.2, < 7.0)
       colorize (~> 0.8)
+      google-api-client (~> 0.34)
       googleauth (~> 0.12)
+      mime-types (~> 3.3)
       nokogiri (~> 1.10)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (6.0.3.1)
+    activesupport (6.0.3.3)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
@@ -22,21 +24,36 @@ GEM
     builder (3.2.4)
     byebug (11.1.3)
     colorize (0.8.1)
-    concurrent-ruby (1.1.6)
+    concurrent-ruby (1.1.7)
+    declarative (0.0.20)
+    declarative-option (0.1.0)
     diffy (3.3.0)
     faraday (1.0.1)
       multipart-post (>= 1.2, < 3)
-    googleauth (0.12.0)
+    google-api-client (0.44.1)
+      addressable (~> 2.5, >= 2.5.1)
+      googleauth (~> 0.9)
+      httpclient (>= 2.8.1, < 3.0)
+      mini_mime (~> 1.0)
+      representable (~> 3.0)
+      retriable (>= 2.0, < 4.0)
+      signet (~> 0.12)
+    googleauth (0.13.1)
       faraday (>= 0.17.3, < 2.0)
       jwt (>= 1.4, < 3.0)
       memoist (~> 0.16)
       multi_json (~> 1.11)
       os (>= 0.9, < 2.0)
       signet (~> 0.14)
-    i18n (1.8.2)
+    httpclient (2.8.3)
+    i18n (1.8.5)
       concurrent-ruby (~> 1.0)
-    jwt (2.2.1)
+    jwt (2.2.2)
     memoist (0.16.2)
+    mime-types (3.3.1)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2020.0512)
+    mini_mime (1.0.2)
     mini_portile2 (2.4.0)
     minitest (5.14.0)
     minitest-reporters (1.4.2)
@@ -44,13 +61,18 @@ GEM
       builder
       minitest (>= 5.0)
       ruby-progressbar
-    multi_json (1.14.1)
+    multi_json (1.15.0)
     multipart-post (2.1.1)
-    nokogiri (1.10.9)
+    nokogiri (1.10.10)
       mini_portile2 (~> 2.4.0)
-    os (1.1.0)
-    public_suffix (4.0.5)
+    os (1.1.1)
+    public_suffix (4.0.6)
     rake (12.3.3)
+    representable (3.0.4)
+      declarative (< 0.1.0)
+      declarative-option (< 0.2.0)
+      uber (< 0.2.0)
+    retriable (3.1.2)
     ruby-progressbar (1.10.1)
     signet (0.14.0)
       addressable (~> 2.3)
@@ -60,7 +82,8 @@ GEM
     thread_safe (0.3.6)
     tzinfo (1.2.7)
       thread_safe (~> 0.1)
-    zeitwerk (2.3.0)
+    uber (0.1.0)
+    zeitwerk (2.4.0)
 
 PLATFORMS
   ruby

data/README.md

@@ -1,6 +1,8 @@
 # AdLocalize
 
-The purpose of this gem is to automatically generate wording files from a csv input (local file or google spreadsheet). It is a useful tool when working on a mobile application or a SPA.
+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.  
 
 ## Installation
 
@@ -26,51 +28,86 @@ $ gem install ad_localize
 
 * Display help
 ```
-$ bundle exec ad_localize -h
+$ ad_localize -h
 ```
 
-* Export wording from a google spreadsheet, using the file key. Make sure to enable _Allow external access_ in sharing options.
+* Export wording from a 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>`.
 ```
-$ bundle exec ad_localize -k <your-spreadsheet-drive-key>
+$ ad_localize -k <your-spreadsheet-drive-key>
 ```
 
-* Export wording from a google spreadsheet, using the file key and specifying a sheet (useful when your file has multiple sheets)
+* Export wording from a set of google spreadsheet tabs.
 ```
-$ bundle exec ad_localize -k <your-spreadsheet-drive-key> -s <your-specific-sheet-id>
+$ ad_localize -k <your-spreadsheet-drive-key> -s <comma-separated-sheet-id-list>
 ```
 
-* Export wording from a private google spreadsheet using a Google Cloud Service Account.
-    1. Create a GCloud Service Account:
-        - Go to [Google Cloud Console](https://console.cloud.google.com/)
-        - 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)
-    2. Enable Google Drive API for the projet
-        - Go to *API / Library* and enable the **Drive API** there.
-    3. 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.
+* Export wording from all sheets in a google spreadsheet. It requires a [Google Cloud Service Account](#using-a-google-cloud-service-account). 
 ```
-$ export GCLOUD_CLIENT_SECRET=$(cat <client-secret.json>)
-$ bundle exec ad_localize -k <your-spreadsheet-drive-key> -a
+$ GCLOUD_CLIENT_SECRET=$(cat <path-to-client-secret.json>) ad_localize -k <your-spreadsheet-drive-key> -e
 ```
 
 * Only generate wording files for the specified platforms
 ```
-$ bundle exec ad_localize -o ios
+$ ad_localize -o ios
 ```
 
 * Choose the path of the output directory
 ```
-$ bundle exec ad_localize -t <path-to-the-output-directory>
+$ ad_localize -t <path-to-the-output-directory>
 ```
 
-* Run in debug mode. In this mode, logs are more verbose and missing values are replaced with "<Missing Translation>"
+* Run in debug mode. In this mode, logs are more verbose
 ```
-$ bundle exec ad_localize -d
+$ ad_localize -d
 ```
 
-### CSV file
-#### General syntax rules
+### In a Ruby program
+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.
+
+```Ruby
+    require 'ad_localize'
+    # create optional google spreasheet options
+    g_spreadsheet_options = AdLocalize::Requests::GSpreadsheetOptions.new(spreadsheet_id: 'some_id', sheet_ids: ['first', 'second'], service_account_config: ENV['GCLOUD_CLIENT_SECRET'])
+    # create export request    
+    export_request = AdLocalize::Requests::ExportRequest.new(g_spreadsheet_options: g_spreadsheet_options, verbose: true)
+    # execute request
+    AdLocalize::Interactors::ExecuteExportRequest.new.call(export_request: export_request)
+```
+
+## Accessing a google spreadsheet
+### Share to anyone with the link
+
+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.
+    
+### Use a Google Cloud Service Account
+
+To use a private google spreasheet you need to use a Google Cloud Service Account. Here are the steps to follow :    
+1. Create a GCloud Service Account:    
+    - Go to [Google Cloud Console](https://console.cloud.google.com/)  
+    - 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)  
+2. Enable Google Spreadsheet API for the project  
+    - Go to *API / Library* and enable the **Drive API** there.  
+3. 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.
+      
+```
+$ GCLOUD_CLIENT_SECRET=$(cat <path-to-client-secrets>) ad_localize -k # one way
+$ GCLOUD_CLIENT_SECRET=$(cat <path-to-client-secrets>) ad_localize -k <your-spreadsheet-drive-key> -s <comma-separated-sheet-id-list> # another way
+```
+
+```
+$ export GCLOUD_CLIENT_SECRET=$(cat <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
+```
+
+## Wording syntax
+### General syntax rules
 
 | key | fr | en |
 | --- | --- | --- |
@@ -78,32 +115,96 @@ $ bundle exec ad_localize -d
 | 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 optional `comment columns)
-- Keys should be written in Android format : [a-z0-9_]+
-- Format specifiers must be numeroted if there are more than one in a translation string (eg: "%1$@ %2$@'s report").
-
+- Any column after the `key` column will be considered as a locale column (except from the optional `comment` 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"`).
 
-#### Comment columns
+### Comments 
 
-In iOS (and only iOS) you can add a comment to a missing translation.
+_Only for Android and iOS_
 
-| key | fr | comment fr | en | comment en |
-| --- | --- | --- | --- | --- |
-| player_time_live | Live | bypass-unused-error | Live | bypass-unused-error |
-| seconds | secondes |  | seconds | bypass-untranslated-error |
+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` :
 
-The comment will be written in the output files  such as below:
+| 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
 ```
 
+### Key with plural notation
+
+_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 |
+
+### String interpolation mapping
+
+_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.
+
+### Adaptive strings
+
+_Only for iOS_
+
+Syntax for [adaptive keys](https://developer.apple.com/documentation/foundation/nsstring/1413104-variantfittingpresentationwidth) in the CSV file: `key##{number}`.
+
+| key | fr |
+| --- | --- |
+| start_countdown##{20} | Start |
+| start_countdown##{25} | Start countdown |
+| start_countdown##{50} | Start countdown |
+
+### InfoPlist.strings
+
+_Only for iOS._
+
+Every key that matches the following formats will be added to the `InfoPlist.strings` file instead of `Localizable.strings`:
+* `NS...UsageDescription`
+* `CF...Name`
+
+### Nested wording
+
+_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 | email |
+
+```json
+{"login":{"password":"mot de passe","email":"email"}} 
+```
+
+```yaml
+fr:
+  login:
+    password: "mot de passe"
+    email: "email"
+```  
+
+
 ## Output
 
-The output folder name is `exports` and it contains a folder for each platform and each locale. In the best case, you just have to replace your existing files with the new ones.
+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/`
 
-Eg:
+Here an export tree example for all supported platforms in `fr` and `en`:
 ```
 exports/
 ├── android
@@ -113,130 +214,32 @@ exports/
 │       └── strings.xml
 ├── ios
 │   ├── en.lproj
+│   │   ├── InfoPlist.strings
 │   │   ├── Localizable.strings
-│   │   ├── Localizable.stringsdict
-|   |   └── InfoPlist.strings
-│   └── fr.lproj
+│   │   └── Localizable.stringsdict
+│   └── fr.lproj
+│       ├── InfoPlist.strings
 │       ├── Localizable.strings
-│       ├── Localizable.stringsdict
-|       └── InfoPlist.strings
+│       └── Localizable.stringsdict
 ├── json
 │   ├── en.json
 │   └── fr.json
+├── properties
+│   ├── en.properties
+│   └── fr.properties
 └── yml
     ├── en.yml
     └── fr.yml
 ```
 
-NB: If you select only one platform, the wording files will directly be generated in the output path. The output path is the `exports` folder in the current directory by default and you can change it using the option `-o`.
-
-## Plurals
-
-Plurals are supported for iOS and Android.
-
-Syntax for plural keys in the CSV file:
-
-       key##{few}
-       key##{one}
-       key##{other}
-       …
-
-Sample of Android output in strings.xml
-
-```xml
-<resources>
-  <plurals name="cake">
-    <item quantity=["zero"|"one"]>gateau</item>
-    <item quantity="other">gateaux</item>
-  </plural>
-</resources>
-```
-
-Sample of iOS output in .stringsdict
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<plist>
-    <dict>
-        <key>traveller_type_child_title</key>
-        <dict>
-            <key>NSStringLocalizedFormatKey</key>
-            <string>%#@key@</string>
-            <key>key</key>
-            <dict>
-                <key>NSStringFormatSpecTypeKey</key>
-                <string>NSStringPluralRuleType</string>
-                <key>NSStringFormatValueTypeKey</key>
-                <string>d</string>
-                <key>zero</key>
-                <string/>
-                <key>one</key>
-                <string>1 enfant</string>
-                <key>two</key>
-                <string/>
-                <key>few</key>
-                <string/>
-                <key>many</key>
-                <string/>
-                <key>other</key>
-                <string>%d enfants</string>
-            </dict>
-        </dict>
-    </dict>
-</plist>
-```
-
-## InfoPlist.strings
-
-_Only for iOS._
-
-Every key that matches the following formats will be added to the `InfoPlist.strings` file instead of `Localizable.strings`:
-* `NS...UsageDescription`
-* `CF...Name`
-
-Source: https://developer.apple.com/documentation/bundleresources/information_property_list
-
-## Adaptive strings
-
-_Only for iOS._
-
-Syntax for adaptive keys in the CSV file:
-
-       key##{20}
-       key##{25}
-       key##{50}
-       …
-
-Sample of iOS output in .stringsdict
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<plist>
-    <dict>
-        <key>start_countdown</key>
-        <dict>
-            <key>NSStringVariableWidthRuleType</key>
-            <dict>
-                <key>20</key>
-                <string>Start</string>
-                <key>25</key>
-                <string>Start countdown</string>
-                <key>50</key>
-                <string>Start countdown</string>
-            </dict>
-        </dict>
-    </dict>
-</plist>
-```
-
-Source: https://developer.apple.com/documentation/foundation/nsstring/1413104-variantfittingpresentationwidth
-
 ## Development
 
 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](https://rubygems.org).
 
+To see all available commands run `bundle exec rake -T` .
+
 ## Contributing
 
 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](http://contributor-covenant.org) code of conduct.