npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@transifex/api

v7.1.3

Published

Transifex API SDK

Downloads

17,471

Readme

Transifex API JavaScript SDK

example workflow npm version documentation

A javascript SDK for the Transifex API (v3)

Intro

This SDK is based on the @transifex/jsonapi SDK library. Most of the functionality is implemented there. If you want to get a better understanding of the capabilities of this SDK, we suggest reading @transifex/jsonapi's documentation.

Setting up

import { transifexApi } from '@transifex/api';

transifexApi.setup({ auth: "..." });

The auth argument should be an API token. You can generate one at https://www.transifex.com/user/settings/api/.

Finding things

To get a list of the organizations your user account has access to, run:

const organizations = transifexApi.Organization.list();
await organizations.fetch();
console.log(organizations.data);

If you have access to many organizations and the first response comes paginated, you can get a list of all organizations with:

for await (const organization of transifexApi.Organization.all()) {
  console.log({ organization });
}

It is highly unlikely that you will have access to so many organizations for the initial response to be paginated but the list and all methods are common to all Transifex API resource types so you might as well get used to them. If the list fits into one response, using all instead of list doesn't have any penalties.

If you want to find a specific organization, you can use the 'slug' filter:

const organizations = transifexApi.Organization.filter({ slug: 'my_org' });
await organizations.fetch();
const organization = organizations.data[0];
// or
const organization = await transifexApi.Organization.get({ slug: 'my_org' });

(get does the same thing as filter(...)[0] but raises an exception if the number of results is not 1.)

Alternatively (if for example you don't know the slug but the name of the organization), you can search against all of them:

let organization;
for await (const o of transifexApi.Organization.all()) {
  if (o.get('name') === 'My Org') {
    organization = o;
    break;
  }
}

After you get an Organization instance, you can access its attributes:

console.log(organization.get('name'));
// <<< 'My organization'

To get a list of projects, do:

const projects = transifexApi.Project.filter({ organization });
await projects.fetch();

However, if you look at how a project is represented in the API docs, Organization objects have a projects relationship with a related link, so you can achieve the same thing with:

const projects = await organization.fetch('projects');
await projects.fetch();

If you look into the API docs, you can see that a slug filter is also supported, so to find a specific project, you can do:

const projects = await organization.fetch('projects');
const project = await projects.get({ slug: 'my_project' });

Projects also have a languages relationship. This means that you can access a project's target languages with:

const languages = await project.fetch('languages');
await languages.fetch();

Changing attributes

Let's use what we've learned so far alongside the API documentation to find a "untranslated string slot" (the /resource_translations endpoint returns items for strings that haven't been translated yet, setting their strings field will post a translation):

const language = await transifexApi.Language.get({ code: 'el' });
const resources = await project.fetch('resources');
const resource = await resources.get({ slug: 'my_resource' });
const translations = transifexApi.ResourceTranslation
  .filter({ resource, language })
  .include('resource_string');
await translations.fetch();
const translation = translations.data[0];

Appending a .include to a filter will pre-fetch a relationship. In the case of ResourceTranslation, this will also fetch the source string information for the "translation slot". Again, you should consult the API documentation to see if including relationships is supported for a given API resource type

In order to save a translation to the server, we use .save:

// We don't have to fetch the resource string because it has been included
const source_string = translation.get('resource_string').get('strings').other;

translation.set('strings', { 'other': source_string + ' in greeeek!!!' });
await translation.save(['strings']);

We have to specify which fields we will be sending to the API with save's argument.

Because this is a common use-case (setting attributes and immediately saving them on the server), there is a shortcut:

await translation.save({ strings: { other: source_string + ' in greeek!!!' } });

Changing relationships

Lets use projects, teams and project languages as examples:

const project = await transifexApi.Project.get({ organization: ..., slug: '...' });
const team_1 = await project.fetch('team');
const team_2 = await transifexApi.Team.get({ slug: '...' });

If we want to change the project's team from team_1 to team_2, we have 2 options:

project.set('team', team_2);
await project.save(['team']);

// Or

await project.save({ team: team_2 });

This is similar to how we change attributes. The other option is:

await project.change('team', team_2);

This will send a PATCH request to /projects/XXX/relationships/team to perform the change. Again, you should consult the API documentation to see which relationships can be changed and with which methods (in this case - changing a project's team - both methods are available).

The project -> team is a "singular relationship" (singular relationships are either one-to-one or foreign-key relationships). To change a "plural relationship", like a project's target languages, you can use the reset, add and remove methods:

const languageDict = {};
for await (const language of transifexApi.Language.all()) {
  languageDict[language.get('code')] = language;
}
const [language_a, language_b, language_c] = [languageDict.a, languageDict.b, languageDict.c];

// This will completely replace the project's target languages
// The project's languages after this will be: ['a', 'b']
await project.reset('languages', [language_a, language_b]);

// This will append the supplied languages to the project's target languages
// The project's languages after this will be: ['a', 'b', 'c']
await project.add('languages', [language_c]);

// This will remove the supplied languages from the project's target languages
// The project's languages after this will be: ['a', 'c']
await project.remove('languages', [language_b]);

The HTTP methods used for reset, add and remove are PATCH, POST and DELETE respectively. As always, you should consult the API documentation to see if the relationship in question is editable and which methods are supported.

Creating and deleting things

The following examples should be self-explanatory.

To create something:

const organizations = transifexApi.Organization.list();
await organizations.fetch();
const organization = organizations.data[0];

const languages = transifexApi.Organization.list();
await languages.fetch();
const language = languages.data[0];

const project = await transifexApi.Project.create({
  name: 'New Project',
  slug: 'new_project',
  private: true,
  organization,
  source_language,
});

You can see which fields are supported in the API documentation. The organization and source_language arguments are interpreted as relationships.

To delete something:

await project.delete();

File uploads and downloads

There is code in @transifex/api that automates several {json:api} interactions behind the scenes in order to help with file uploads and downloads.

In order to upload a source file to a resource, you can do:

const content = JSON.stringify({ key: 'A value' });
await transifexApi.ResourceStringsAsyncUpload.upload({
  resource,
  content,
});

In order to upload a translation file to a resource, you can do:

const content = JSON.stringify({ key: 'A value in French' });
const language = await transifexApi.Language.get({ code: 'fr' });
await transifexApi.ResourceTranslationsAsyncUpload.upload({
  resource,
  language,
  content,
});

To upload binary files, convert file content to base64 encoding:

await transifexApi.ResourceTranslationsAsyncUpload.upload({
  resource,
  language,
  content, // base64 encoded string
  content_encoding: 'base64',
});

In order to download a translated language file, you can do:

const language = await transifexApi.Language.get({ code: 'fr' });
const url = await transifexApi.ResourceTranslationsAsyncDownload.download({
  resource,
  language,
});
const response = await axios.get(url);
console.log(response.data);

As always, in order to see how file uploads and downloads work in the Transifex API, you should check out the API documentation.