Utilities to perform tasks on OneSky


1.0.27 months ago3 years agoMinified + gzip package size for @finderly/onesky in KB


OneSky CLI

Utilities to perform tasks on OneSky

This tool currently supports working with translations stored in JSON or YAML files. Support for XML and Apple's strings file formats are coming soon.


npm install @finderly/onesky


To use this utility you will need your OneSky API keys. You can find these by following the guide in this article: How to find your API keys.

The API keys should be stored in a file called .oneskyrc located in your project or home directory. The file contents look like this:

❯ cat $HOME/.oneskyrc
  publicKey: "your_public_key_here",
  privateKey: "your_private_key_here"

Private key is also known as secret key


Usage: onesky [options] [command]


    -h, --help  output usage information


    download    download message files
    upload      upload message files
    sync        fetch, merge then upload message files
    help [cmd]  display help for [cmd]



Download a OneSky source file's translations in a given locale.


onesky download \
    --id 123456 \
    --source messages.json \
    --locale it \
    --destination languages/it.json \

The --force is used to overwrite the local file if it already exists


Upload translations for a OneSky source file. The --locale flag specifies which language the local file being upload represents.

Note: You need to upload a source file's translations for the base language of your project before uploading it for any other locales


onesky upload \
    --id 123456 \
    --name en.json \
    --path locale/en/messages.json \
    --locale en \

When uploading a file to OneSky the file name will be determined using the value of --path by default (in this case the file name would be messages.json). However, you can override by passing the --name flag. In the above example, the command will upload a file called en.json with contents coming from locale/en/messages.json.

The --wait flag causes the CLI to wait for OneSky to complete the import of the file.


Sync is a workflow command that does three things:

  • Downloads all translations for a given file on OneSky, identified by --source
  • Merges the downloaded translations with ones located locally. It uses --pattern to find locale files.
  • Uploads the merged results back up to OneSky

Running this command periodically creates a tight workflow in which new translations are downloaded and missing translations are submitted up to OneSky for translators to fill out.


onesky sync \
    --id 123456 \
    --pattern 'locale/[lang]/messages.json' \
    --source myapp.json

The --pattern is the key part in this command. It can be any path pattern and must contain at least one instance of the [lang] token. In the example above if a OneSky project has three languages - such as it, en, de - then the command will sync files at the following locations with the translations for the myapp.json source file:


If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.