npm package: @panter/transporter
Description: Sync translations between Airtable and JSON files.
Latest version: 0.0.10

# TransPorter

Sync translations between Airtable and JSON files.

The currently intended workflow is for doing manual updates via developers, so that the changes are inlcuded in version control. This workflow can be improved (like circumventing a developer's involvement) in future iterations.

## Usage

Use `npx transporter pull` and `npx transporter push`. The intended workflows are:

#### Pull
1. Client updates the translations on Airtable and notifies a dev when they are done.
2. The dev pulls.

Pull overrides local changes and creates _old file for reference. The changes are to be merged manually and pushed.

#### Push
1. A dev adds a feature with new translation keys. They add it to the translations files.
2. The dev pulls and syncs with changes done on Airtable.
3. The dev pushes.

Push overrides Airtable changes. Remember to pull before pushing.

## Getting started

1) Create a new base in Airtable. Prepare a new table for Translations with a column for key e.g. `Name` (it's default, could be change in config) and columns named in locale codes (DE, EN, etc.) for translations.
2) Create Personal access token with scopes `data.records:read`, `data.records:write` in Airtable Developer-hub and ensure that it is in env variable `AIRTABLE_API_KEY`. Add your base to the token at https://airtable.com/create/tokens.
3) Create `transporter.config.js` in the root of your module and fill the config based on the example below.
4) Run `npx transporter pull` or `npx transporter push`

### Config
Needs to be filled. Example:
```ts
import { Config } from "@panter/transporter";

const config: Config = {
  airtable: {
    baseId: "<ID_HASH>",
    tableId: "<ID_HASH>",
    keyColumName: "Name",
    delimiter: ".",
  },
  langs: ["DE", "EN"],
  sections: [
    {
      transPath: "./public/locales",
      translationName: "common",
      airtable: {
        tableId: "<ID_HASH>",
        keyColumName: "Name",
        delimiter: ".",
      },
    },
    {
      transPath: "./public/locales",
      translationName: "admin",
      airtable: {
        tableId: "<ID_HASH>",
        keyColumName: "Name",
        delimiter: ".",
      },
    },
  ],
};

export default config;
```

- `keyColumName` name for a column with keys for JSON object
- `delimiter` is used for flatting JSON objects to key + value pairs. `.` => (`ra.action.save`)
- `langs` array of locales which is in Airtable
- `sections` array LocaleSections
- `LocaleSection`: for more separated files for translations

```js
  transPath: string;
  translationName: string;
  includedPrefixes?: string[];
  excludePrefixes?: string[];
```
Example Airtable base for this config:

![Alt text](airtableTableExample.png)

Airtable URL structure:
https://airtable.com/<BASE_ID>/<TABLE_ID>/<VIEW_ID>
E.g. https://airtable.com/appmyLk487SgURjgz/tblMtQPWNWCTO1lce/viw2ahFCeyvw6ufpd

### CLI
After installing run:
```bash
npx transporter
```
You could use `push` and `pull` commands with parameters to overwrite config values.
```bash
  -b, --base-id <table-id>   [Optional]  Base id.
  -t, --table-id <table-id>  [Optional]  Table id.
  --view-id <string>         [Optional]  View id.
```
```bash
npx transporter push -t XXXXXX
npx transporter pull -t XXXX -b XXXXX
```

### Outputs
Command `pull` overwrite your files, if exists create a backup with suffix `_old`. Also if there are some records without key or value, create log files with these records.


### Limits
1. Free namespaces are limited to 1,2k records. You need to split your records to another base or buy a new plan to increase it.
Price tiers: https://airtable.com/pricing
1. Create/update records is limited 10 per request - could take a while.