Qordoba CLI

Qordoba CLI client installation and command summary

Introduction

The Qordoba CLI client, known as "the client" from here on, is a command line utility for copying and synchronizing project files between Qordoba and your local host.

Installation

Option 1:

The client uses pip commands for housekeeping. Please have both python and pip installed and available in the system PATH.

pip install qordoba
pip install qordoba -U

Option 2:

1. [Download](https://github.com/Qordobacode/qordoba-cli/tree/master)
2. Unpack
3. cd into directory
4. pip install .

Python Packages

Source

Next step: Authenticating

When you connect to a Qordoba project from your local host, you'll need to authenticate with your Organization ID, Project ID, and Account Token.

Option 1: Connecting over command line (not recommended)

If you do not set up the configuration file, you must enter these option-value pairs on the command line.

  1. On Qordoba.com, select Projects > Settings, and click the CLI Config tab. Get the Organization ID, Project ID, and Account Token values.
  2. On your host computer command line, cd to your project directory.
  3. Execute the qor init command with the following option-value pairs and choose a project type number:
    • --organization-id followed by the Organization ID value.
    • --access-token followed by the Account Token value.
    • --project-id followed by the Project ID value.

Note: If you did set up the configuration file, and you enter these option-value pairs on the command line, the values from the command line temporarily override the values in the configuration file.

$ qor init --organization-id 1234 --access-token 10c7f4cb7e1df2d817a0e9e28391ad9c6f22d --project-id 4422
-> Loading qordoba config...
-> Checking organization and project...
-> Config `/Users/Qordoba/localization/.qordoba.yml` successfully saved.

Option 2: Connecting via config.yml (recommended)

Step 1: download the client configuration file that contains the --organization-id, project-id and --access-token options, along with their values. Specific commands require those option-value pairs to authenticate when they connect to the Qordoba server and access your project. Using the configuration file saves you from re-entering those option-value pairs on the command line.

On Qordoba.com, select  Projects > Settings, and click the CLI Config tab.

On Qordoba.com, select Projects > Settings, and click the CLI Config tab.

Before you can connect to Qordoba you have to do the following two steps:

Step 2: move your downloaded configuration file and optionally set an environment variable.

`qordoba` will look for its configuration file in the following order:

1. At the path specified in the environment variable `QORDOBA_CONFIG`.
2. In the current working directory as hidden file `.qordoba.yml`.
3. In the user's home directory as hidden file `.qordoba.yml`.

Step 3: rename the filename from config.yaml to .qordoba.yml.

Step 4: edit (optional) Later, after setting up the configuration file, you can edit the configuration file to change or add other option-value pairs. As shown you can define the source and target paths.

qordoba: 
  access_token: 10c7f4cb7e1df2d817a0e9e28391ad9c6f22d
  organization_id: 1234
  project_id: 12321
       
  #Versions after 1.2.0:
  push:
    sources:
    - "./source/*.yml" 
  pull:
    targets:
    - "./<language_code>/<filename>.<extension>"
    
  #Versions prior to 1.1.9:
  push:
    sources:
    - file: "./source/*.yml" 
  pull:
    targets:
    - file: "./<language_code>/<filename>.<extension>"
 
qordoba:
  access_token: 10c7f4cb7e1df2d817a0e9e280a8391ad9c6f22d 
  organization_id: 1234
  project_id: 12321
  
  #Versions prior to 1.1.9:
  push:
    sources:
    - file: "./res/values-/strings.xml" 
  pull:
    targets:
     - file: "./<language_code>/<filename>.<extension>"
     
  #Versions after 1.2.0:
  push:
    sources:
    - "./res/values-/strings.xml" 
  pull:
    targets:
     - "./<language_code>/<filename>.<extension>"
qordoba:
  access_token:  
  organization_id: 1234
  project_id: 12321

#Versions prior to 1.1.9:  
  push:
    sources:
    - file: "./.lproj/Localizable.strings"
  pull:
    targets:
     - file: "./<language_code>/<filename>.<extension>"
    
#Versions after 1.2.0:
  push:
    sources:
    - "./.lproj/Localizable.strings"
  pull:
    targets:
     - "./<language_code>/<filename>.<extension>"

Fileformats:
allows to add custom file formats in config file

Push: sources: file:
will use this file path if none is specified on the command line.
example to push all json files: -file: "./source/*.json"
example to push single json file: -file: "./source/english.json"

Pull: targets: file:
recognizes the following patterns:

Default pattern for pull:

<language_code>.<extension>

Available params in pattern:

<language_code> - full code like en-us
<language_lang_code> - only language part without count - en
<language_name> - language name like english
<language_name_cap> - capitalized language name - English
<language_name_allcap> - uppercase language name - ENGLISH
<local_capitalized> - uppercase local name - US version 1.5.5

Pull: single files from specific workflow step/milestone:

with the flag --workflow (Version 1.2.2) files from project internal workflow steps can be pulled.

Pull: all files from specific workflow step/milestone:

with the flag --workflow-all WORKFLOWSTEP (Version 1.3.9) files from project internal workflow steps can be pulled. (name of the workflow step is a required argument)

Pull: files and save with custom extension:

with the flag --custom (Version 1.2.8) all (no matter what file format) completed files from the project will be saved with the custom extension defined within the config file

use case: the file format within the Qordorba platform is POT but you want to save the files as PO file format

.qordoba.yml

qordoba:
access_token: 10c7f4cb7e1df2d817a0e9e28391ad9c6f22d
organization_id: 1234
project_id: 12321

Versions after 1.2.8:

pull:
targets:

- "./irgendwas/<filename>.po"

Pull: distinct: file:

with the flag --distinct and the specific file path in the config the CLI will pull specific files from your project (Version 1.2.0). The distinct flag will not work for files which are saved in Qordoba with file paths.

example config for --distinct:

  push:
    sources:
      - '../../source/*' #push everthing 
      - '../../source/*.json' #push only json sources 
      - '../../source/*' #push all files in folder
  pull:
    targets: #pull folder structer with different filenames or filer versions
      - '../../folder/business_marille.json'
      - '../../folder/plans/enterprise/enterprise_marille.json'
      - '../../folder/plans/free/free_marille.json'
      - '../../folder/plans/plans_marille.json'
      - '../../folder/plans/pro/pro_marille.json'

example config (default, no flags):

  push:
    sources:
      - '../../source/*' #push everthing 
      - '../../source/*.json' #push only json sources 
  pull:
    targets: #pull folder structer with different filenames or filer versions
      - 'locales/server.<language_code>.yml'
      - 'filenames/server.<filename>.yml
      - 'all_extension/<filename>.<extension>

Examples:

i18n/<language_code>/translations.json  ->  i18n/zh-cn/translations.json
folder1/values-<language_lang_code>/strings.xml  ->  folder1/values-en/strings.xml
config/locales/server.<language_code>.yml  ->  config/locales/server.fr-fr.yml
folder2/<language_name>/strings.xml  ->  folder2/Chinese/strings.xml
folder3/strings.<language_name_cap>  ->  folder3/strings.French
<language_name_allcap>.locale  ->  FRENCH.locale

Due to Apples naming convention for iOS we have implemented an additional feature.
By configuring config pull as the bottom example, the exception folder names will be pulled with new names: zh-Hans, zh-Hant, pt-BR, zh-CN (before: zh-chs, zh-cht, pt-br, zh-cn)

qordoba: 
  access_token: 
  organization_id: 1234
  project_id: 12321
  push:
    sources:
    - "./*.Strings"
  pull:
    targets:
    - "./<language_lang_code>.lproj/<filename>.<extension>"

Managing project files between Qordoba and your local host

Command-Options

The following options work with qor (qordoba) and any other command on this page.

--access-token

  • Required by the push and delete commands to authenticate a connection to qordoba.com.
  • Must be defined in the .qordoba.yml configuration file or entered on the command line.
  • Passes the Account Token value
  • Example: $ qor init --organization-id 1234 --access-token 10c7f4cb7e1df2d817a0e9e28391ad9c6f22d

--debug

  • Optional. Enables debug messages for any command.
  • Example: $ qor init --organization-id 1234 --access-token 10c7f4cb7e1df2d817a0e9e28391ad9c6f22d

Generates a step-by-step report of the executed command. The report includes the contents of the files to be processed. For example:

$ qor --debug push -s 
  Path` to qordoba is `/Users//`. 
  Config file is `/Users///.qordoba/config` 
  .qordoba file is at /Users/ 
  Language mapping is: Flipdict({}) 
  Using host https://api.qordoba.com/cli/v2/ 
  Pushing translations for resource . 
  Statistics response is { "en_US": { "reviewed_percentage": "0%", "completed": "100%", ........etc } }

--help

  • Optional. Displays help for any command and option.
  • Example A: To display a list of commands, enter qordoba --help, as shown here.
$ qor --help
usage: qordoba [-h] {init,status,pull,push,ls,delete} ...

root parser

positional arguments:
  {init,status,pull,push,ls,delete}
                        subparser group
    init
    status
    pull                Use the pull command to download locale files from the
                        project.
    push                Use the push command to upload your local files to the
                        project.
    ls
    delete

optional arguments:
  -h, --help            show this help message and exit
  • Example B: To display a list of options for any command, enter the command followed by --help, as shown here.
$ qor init --help
usage: qordoba init [-h] --organization-id ORGANIZATION_ID
                                   --access-token ACCESS_TOKEN
                                   [--project-id PROJECT_ID]
                                   [--file-format {YAMLi18n,androidXML,macStrings}]
                                   [--traceback] [--debug] [--force]

optional arguments:
  -h, --help            show this help message and exit
  --organization-id ORGANIZATION_ID
                        The ID of your Qordoba organization
  --access-token ACCESS_TOKEN
                        Your Qordoba access token
  --project-id PROJECT_ID
                        The ID of your Qordoba project
  --file-format {YAMLi18n,androidXML,macStrings}
  --traceback
  --debug
  --force

--organization-id

  • Required by the push and delete commands to authenticate a connection to qordoba.com.
  • Must be defined in the .qordoba.yml configuration file or entered on the command line.
  • Passes the Organization ID value.
  • Example: $ qor init --organization-id 1234 --access-token 10c7f4cb7e1df2d817a0e9e28391ad9c6f22d

--project-id

  • Required by the push and delete commands to authenticate a connection to qordoba.com.
  • Must be defined in the .qordoba.yml configuration file or entered on the command line.
  • Passes the Project ID value.
  • Example: $ qor init --organization-id 1234 --access-token 10c7f4cb7e1df2d817a0e9e28391ad9c6f22d --project-id 4321`

--traceback

  • Optional. Displays full tracebacks on exceptions/errors from running a command. Helps identify mistakes in resource files.
  • Example: $ qor init --organization-id 1234 --access-token 10c7f4cb7e1df2d817a0e9e28391ad9c6f22d --project-id 4321 --traceback`

Command Reference

delete

Deletes any resource and its translations. Your user account must have admin privileges to run this command.

Options/Arguments
Description

-f --force

Optional. Force deletion of the remote page and its translations. Do not ask for approval.

a filename or filenames

Required. The filename or filenames to delete. Use commas to separate multiple filenames. Do not specify the translated files.

-l

Optional. To delete one or more translations use the -l option with the list of languages to remove.

For example:

$ qor delete -l <file paths or file ids>

The client will not delete resources or languages that contain translations. To force the deletion, use the `-f`` option.

$ qor delete -f <file paths or file ids>

init

Creates a basic configuration file, .qordoba.yml, in the current directory. This file is required for the client to connect to the server and synchronize files. See Configuration.

Option
Description

--project-id

(Required) Save the Project ID to the configuration file.

--access-token

(Required) Save the Account Token to the configuration file.

--organization-id

(Optional) Save the Organization ID to config file

--force

(Optional) Recreate config file, overwriting the previous one.

ls

Lists remote files.

$ qor ls

-> Loading qordoba config...
+--------+-----------------+-----------+---------------------+---------+
| ID     | NAME            | #SEGMENTS | UPDATED_ON          | STATUS  |
+--------+-----------------+-----------+---------------------+---------+
| 728068 | runtime.yaml    | 6         | 2017-01-20 10:19:27 | Enabled |
| 725570 | TestFileMH.json | 26        | 2016-12-21 22:40:13 | Enabled |
+--------+-----------------+-----------+---------------------+---------+

pull

Downloads translations for registered source files.

Option
Description

-w --workflow

(Optional) Allow to download not completed translations. Will ask for feedback on workflowstep. By default - download only completed translations.

-l --languages

(Optional) Option to work only on specific (comma-separated) languages
Examples:

    ./qor -l ru,en
    ./qor -lzh-cn
qor -len_US,ru,zh-cn

-f --force

(Optional) Force to update local files by remote translations. Do not ask approval.

--skip

Skip downloading if file exists. (default: False)

--replace

Replace existing file. (default: False)

--set-new

Ask to set new filename if file exists. (default: False)

--bulk

Speeds to the pull command:
Pulls translated files in bulk, including the source language. Will automatically create a directory 'bulk_download' and store all translations files plus source files in it. No custom configuration of pull pattern possible

push

Uploads local project files that contain untranslated strings. Use the push command to upload your locale files to the project identified by project_id, matching the files de.yml and en.yml in the config/locales folder:

qor push
Push all local source files to the Qordoba project. 

*files
	(Optional). Lists the file paths to upload.
--update
	(Optional). Updates an existing file.
--version
	(Optional). Sets the version tag. Updates the file with version tag. Uploads a  file with the version tag

status

Displays the status of localization work on the current project. It lists the resources initialized under the local project and their associated translation files.

use qor status --json if you want the output to be in json format instead of a table

$ qor status
-> Loading qordoba config...
+--------+--------+-----------+---------+--------------+-----------+
| LOCALE | #WORDS | #SEGMENTS | EDITING | PROOFREADING | COMPLETED |
+--------+--------+-----------+---------+--------------+-----------+
| ja-jp  | 94     | 32        | 0%      | 78.13%       | 21.88%    |
| es-es  | 94     | 32        | 100%    | 0%           | 0%        |
+--------+--------+-----------+---------+--------------+-----------+
  • LOCALE: The language code and country code separated by a dash. See Languages
  • #WORDS: The number of words per locale.
  • #SEGMENTS: The number of segments per locale
  • TRANSLATION: If proofreading is one of the steps in the project workflow, the percentage of work completed on the translation step.
  • EDITING: If proofreading is one of the steps in the project workflow, the percentage of editing work completed.
  • PROOFREADING: If proofreading is one of the steps in the project workflow, the percentage of proofreading work completed.
  • COMPLETED: The percentage of all project work completed.

Push and pull file paths to and from Qordoba (beta)

If you have multiple project folders which all contain a file named e.g. "index.html". Pushing the same file to Qordoba would not work without giving a version tag. Now, we provide a - still- very simple functionality to solve your issue.

We will elaborate the feature on the following use case:

Example of your folder structure:

partials/en/index.html
html/en/index.html
  1. Push your files including your relative folder path (relative to where your configuration file .qordoba.yml is located):
`qor push --file-path`
  1. Pull your files back into the same folder structure. (The config needs to be at the same place as for the push).

a) Add a flag: Depending on your folder naming one of these abbreviations will need to be added as a flag:

<language_code> - en-us
<language_lang_code> - en
<language_name> - english
<language_name_cap> - English
<language_name_allcap> - ENGLISH
<local_capitalized> - US

For the example folders, the command will be:

`qor pull --file-path-pattern language_lang_code`

As you can see your folder path ../en/.. match with the <language_lang_code> abbreviation

b) if you want to use the default please use command qor pull --file-path default.

For the given example this will end in:

partials/en/de-de-index.html
html/en/de-de-index.html

** tested on mac only