npm package: @finderly/onesky
Description: Utilities to perform tasks on OneSky
Author: Georges Haidar
Latest version: 1.0.2

# OneSky CLI

Utilities to perform tasks on [OneSky][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._

## Install

```sh
npm install @finderly/onesky
```

## Prerequisites

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][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

```
Usage: onesky [options] [command]

Options:

	-h, --help  output usage information

Commands:

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

## Commands

- [download](#download)
- [upload](#upload)
- [sync](#sync)

### download

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

Example:

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

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

### upload

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

Example:

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

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

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.

Example:

```sh
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:

```
locale/en/messages.json
locale/de/messages.json
locale/it/messages.json
```

[onesky]: https://www.oneskyapp.com/
[api-keys]: https://support.oneskyapp.com/hc/en-us/articles/206887797-How-to-find-your-API-keys-