@panter/transporter

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:

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

  transPath: string;
  translationName: string;
  includedPrefixes?: string[];
  excludePrefixes?: string[];

Example Airtable base for this config:

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

CLI

After installing run:

npx transporter

You could use push and pull commands with parameters to overwrite config values.

  -b, --base-id <table-id>   [Optional]  Base id.
  -t, --table-id <table-id>  [Optional]  Table id.
  --view-id <string>         [Optional]  View id.

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
2. Create/update records is limited 10 per request - could take a while.