Gitpo NPM | npm.io

GITPO

Small utility to manage translations for POEditor projects linked to GitHub repositories: trigger import/export/sync... webhooks manually or programatically.

This is not a full API client and does not intend to be. For this you should checkout node-poeditor or other solutions.

Install

yarn add gitpo

Add a .gitporc with the followings:

{
  "API_TOKEN": "<your POEditor API key>",
  "HOOKS": {
    "<projectId>": {
      "IMPORT": "<webhook_url>",
      "SYNC": "<webhook_url>",
      "EXPORT": {
        "fr": "<webhook_url>",
        "en": "<webhook_url>"
      }
    }
  }
}

The HOOKS need to be defined on POEditor, this is due to a change on POEditor's side which prevent us from building the hooks url or creating them automatically through API calls. Check POEditor WebHooks guide for more information.

Usage

CLI Usage

This package provide a CLI powered by Inquirer

? What would you like to do: (Use arrow keys)
❯ View Project Details
  Update Code (POEditor → GitHub)
  Update POEditor (GitHub → POEditor)
  Remove default Translations
  Manage contributors

You'll be able to trigger webhooks from POEditor to run associated actions.

Remove default Translations is a utility to which you need to pass a JSON file path and that will remove values that are the same as the keys. eg:

{
  "hello world": "hello world",
  "this key will not be cleaned": "because the value is different"
}

will be turned into

{
  "hello world": "",
  "this key will not be cleaned": "because the value is different"
}

As we use gettext based i18n solution and english fallback in our transaltion files, this help remove english fallbacks from our output files when we need to reprocess them.

Programatical Usage

const {
  addContributor,
  cleanTranslationJSON,
  importNewTerms,
  listContributors,
  listProjectLanguages,
  listProjects,
  removeContributor,
  synchronizeTerms,
  updateTranslations,
  viewProject
} = require("gitpo");

const languages = await listProjectLanguages(projectId);
console.log(languages);

// [
//   { name: 'English',
//     code: 'en',
//     translations: 2067,
//     percentage: 100,
//     updated: '2017-11-16T09:14:45+0000' },
//   { name: 'French',
//     code: 'fr',
//     translations: 1456,
//     percentage: 70.44,
//     updated: '2017-11-16T11:33:54+0000' },
// ]

Reference

All functions are async and return a Promise.

Utility

cleanTranslationJSON(file, override)

Type	Param	Description
String	`file`	is a path to the file to clean
Bool	`override`	should override the existing file or not, default to `false`

Clean JSON translation file of any default value:

{
  "hello world": "hello world",
  "this key will not be cleaned": "because the value is different"
}

will be turned into

{
  "hello world": "",
  "this key will not be cleaned": "because the value is different"
}

It will create a file next to the input if override is set to false, eg: en.json → en.clean.json)

Webhooks

Manual trigger of webhooks to update POEditor from a Github repository & vice versa.

importNewTerms(projectId)

Type	Param	Description
Number	`projectId`	The POEditor project id

Run the import_translations webhook on the given project (see: POEdtor Webhook Documentation)

synchronizeTerms(projectId)

Type	Param	Description
Number	`projectId`	The POEditor project id

Run the sync_terms_and_translations webhook on the given project (see: POEdtor Webhook Documentation)

updateTranslations(projectId, languages)

Type	Param	Description
Number	`projectId`	The POEditor project id
Array	`languages`	List of language code

Run the export_terms_and_translations webhook on the given project and languages (see: POEdtor Webhook Documentation)

:warning: To complete this action, one call per language will be made.

API

listProjectLanguages(projectId)

Type	Param	Description
Number	`projectId`	The POEditor project id

List languages for a given project (see: POEdtor API Documentation)

Example of value returned on Promise.resolve

[
  {
    "name": "English",
    "code": "en",
    "translations": 2067,
    "percentage": 100,
    "updated": "2017-11-16T09:14:45+0000"
  },
  {
    "name": "French",
    "code": "fr",
    "translations": 1456,
    "percentage": 70.44,
    "updated": "2017-11-16T11:33:54+0000"
  }
]

listProjects()

List projects you can access (see: POEdtor API Documentation)

Example of value returned on Promise.resolve

[
  {
    "id": 1111,
    "name": "Project Name",
    "public": 0,
    "open": 0,
    "created": "2014-06-06T12:00:00+0000"
  }
]

viewProject(projectId)

Type	Param	Description
Number	`projectId`	The POEditor project id

Get the details of a given project (see: POEdtor API Documentation)

Example of value returned on Promise.resolve

[
  {
    "id": 1111,
    "name": "Project Name",
    "public": 0,
    "open": 0,
    "created": "2014-06-06T12:00:00+0000"
  }
]

listContributors()

List contributors to your projects

Example of value returned on Promise.resolve

[
  {
    "name": "Alice",
    "email": "alice@example.com",
    "permissions": [
      {
        "project": {
          "id": 1111,
          "name": "Project Name"
        },
        "type": "administrator"
      }
    ],
    "created": "2014-06-06T12:00:00+0000"
  },
  {
    "name": "Bob",
    "email": "bob@example.com",
    "permissions": [
      {
        "project": {
          "id": 1111,
          "name": "Project Name"
        },
        "type": "contributor",
        "languages": ["fr", "en"]
      }
    ],
    "created": "2014-06-06T12:00:00+0000"
  }
]

addContributors(email, fullname, projects, languages)

Type	Param	Description
String	`email`	Contributor's email address
String	`fullname`	Contributor's fullname
Array	`projects`	List of POEditor project id
Array	`languages`	List of language code