Image for post
Image for post

Help Us Translate the State of JavaScript Survey Results

(Updated for the 2019 Edition)

Sacha Greif
Dec 10, 2018 · 3 min read

Numbers may be a universal language, yet if you don’t read English you’ll still miss out on a lot of insights from the latest State of JS survey. For that reason we’ve decided to start translating our results in as many languages as possible!

We’re doing this as a crowdsourced, community effort, and in fact we’ve already heard from many volunteers interested in helping us translate!

The Workflow

If you’d like to help, here’s some more information about the workflow we’ve implemented. Let’s say Alicia wants to translate our results to Spanish.

Starting a New Language

  1. Alicia forks the State of JS 2019 repo to her own GitHub account.
  2. She makes an initial commit modifying the languages files (see below for information on where to find them).
  3. She then opens a PR back to the root repo.
  4. In the PR description, she pastes in this list of to-do items to help others see how far the translation has progressed.

Contributing to an Existing Language

Now let’s say Javier comes along, and he wants to help with the Spanish translation effort. He would:

  1. Search the list of open PRs for any pending Spanish translations.
  2. Leave a comment on the PR asking for write access to Alicia’s fork (which can be given in the repo’s Settings > Collaborators & teams screen).
  3. Once Javier has write permissions, he can now add commits directly to the PR.

Finalizing a Language

  1. Once a language is complete, Alicia can ask me (SachaG) to review and merge the PR.

This means that the first person to start a new translation PR will become the “manager” for that language and be responsible with adding collaborators and notifying us once all collaborators are happy with the result.

Language Files

Translation files are located in /src/translations. Each language has the following files:

  • A root locale.yml file (for exampe en-US.yml) containing all user interface translations.
  • A locale directory (for example /en-US/) containing all markdown files for introductions, conclusions, etc.

When contributing new translations, please make sure you follow the same directory and file structure!

To enable a translation you also have to add your locale to config/locales.yml .

Other i18n Work

Internationalization is not just about translation, but also involves making other changes like loading new fonts, or adding right-to-left language support.

For these changes, please open separate PRs to make the reviewing process easier.

Running the Site Locally

You might want to see what your translations look like in the actual site. To do so you can run it locally with gatsby develop.

Note though that this will require access to our internal GraphQL API. While it’s not officially public yet (we don’t really have a good caching layer or any documentation in place) here are some instructions on how to connect to it:

  • In the root of the State of JS 2019 Gatsby repo, create a new .env file.
  • Add the following line to it:
API_URL=https://stateofjs-api.herokuapp.com/

If you have any questions about using the API you can check out this GitHub issue (the API has its own separate repo).

Note that since this is a fairly large Gatsby site with a lot of API queries, 30s-1min build times are not out of the ordinary.

Also, if you’d like to trigger a clean rebuild with a clear cache you can use:

npm run dev:clean

Previous Years Translations

You can find the translation files for the 2018 edition here. A lot has changed since last year so it might not be that straightforward to reuse the same translation strings. In the future we might explore a more sustainable translation workflow that doesn’t require starting from scratch again every time.

Other Questions

For any other question, please open an issue on GitHub!

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store