Website Internationalization Roadmap

[orta]

As the new website is being built out bit-by-bit, we're adding support for internationalized content on a per-section basis. I've been working with l33t speak under the language "vo" to test out the infra as it is built.

I expect there are (at least) four main components for creating content on a per-language basis:

• Website copy (navigation bar, index page, community page etc)
• Website (and handbook) content (markdown files mainly)
• Playground examples content, and on-screen copy
• TSConfig reference content, and on-screen copy

Each one of these needs:

• Working English documentation as reference
• Infra for supporting the creation of internalized content
• Infra for supporting the presentation of internationalized content

Current state of internationalization:

• Website copy.

  • English
  • Creation
  • Users

• Website content (e.g. the handbook).

  • English
  • Creation
  • Users

• Playground examples:

  • English
  • Creation
  • Users

• TSConfig:

  • English
  • Creation
  • Users

How To Contribute

1. Join the TypeScript Discord - come say hi the ts-web-translate

2. Clone the repo. The work will happen on the v2 branch. Deploys of the TS website have this static site set up at http://www.typescriptlang.org/v2/

git clone https://github.com/microsoft/TypeScript-Website
cd TypeScript-Website

code .
code README.md

# Follow setup instructions in README
# then start up the server
yarn start

3. Look below to see the sections, then come back up here

4. Read this PR to see an example of adding a language: Create an example PR which shows how to add a language #181

5. Pick one of the below sections to start with, it might be easiest to work with samples in the Playground first FWIW.

Website

The website supports localization via React-intl, as of today only the navigation bar it translatable, but with time this will grow. The infra just came in with #180

There are a series of keys and values for each language, with a fallback to English if you miss something. The TypeScript compiler will keep it all in check.

Playground

You can cover the examples in the dropdown in the playground (and in the site footer on desktops.) Full docs here

• Make a subfolder with the code of the language in the copy folder of the 'playground-examples'
• Ensure the filename are the same as English, (you can provide a different title via the JSON headers in the ts/js files)

TSConfig

Each TSConfig file is a unique markdown file which can be uniquely handled per language. Any markdown file not found will be replaced with English. Full docs here

• Check out this folder
• Ensure the filename is the same (we can provide a different title via the YML headers in the markdown files)

---

Recommendations

I'm pretty new to the translation game, but here's some notes from working with people so far on how translations can culturally work in the TS website.

Translate code to be a cultural fit. E.g.

const helloWorld = "Hi" 

to

const olaMundo = "Olá`

Translate names in example

const user =  { name: "John" }

to

const usar =  { name: "João" }

Note: we aim to have a diverse set of nationalities and genders in our examples, so I'd recommend not changing all of them, but try keep it feeling like it was written with that in mind also.

Translate Technical Terms, but keep English around

This one is nuanced, but a term like Mapped Type is the name for this:

type MyPartialType<Type> = {
  // For every existing property inside the type of Type
  // convert it to be a ?: version
  [Property in keyof Type]?: Type[Property];
};

So, if you translate it to "mapeada type", then provide a reference to the original name the first time it is used: "mapeada type (Mapped Type em inglês)" so that readers can know how to find the English resources on a topic.

[orta]

My long term goal will be to support the same style of infra which Gatsby and React use. Example. That requires having a full site ready with existing content for folks to work from - so it'll be piecemeal as I built it out

[orta]

#163 adds the ability to create and present internationalized playground samples

[glaucia86]

@orta hi! I was talking to Daniel, that you can count on me about to translate this pages to Portuguese. :)

[orta]

Woooo!

[Naturalclar]

@orta
Hello! I can help translating the website into Japanese :)

[evanSe]

Hey @orta I would like to help out, are there any parts that still need internationalization support? (code wise) as I only know English so translations would be useless 😅

[orta]

Hi @evanSe - Yeah, there's still quite a lot of English text in JSX which hasn't moved to the internationalization pattern yet!

For example there's the 'documentation' page (code), the same with the playground/tsx/handbook templates too

Here's an example of how the i8n works in the topnav as a reference

• Create a file for the template
• Link that to the english language
• Create an i function in the React component
• Use i("key")to get the text

Documentation is a solid place to start, think about bits which would change between languages (subheadings probably) vs which would never "React", "Angular" etc

[orta]

#790 wraps up localizing docs content (e.g. the handbook etc), at this point every page and string should be localized or localizable.

If it's not, that's my fault and generally 'getting it shipped'-ness for the site. I'm going to start making a list of 'safe to translate' docs later in the week which means we're not planning on making changes to the actual content of the page.

[orta]

My general recommendations for reviewing localization are:

• Does it provide enough english technical terms that you could google for the answer in English?
• Is it readable without a deep knowledge of computer science?
• Does it avoid overly gendered language?
• Did you feel like you learned something from it?
• General typoes etc I'm not too worried about, people will send PRs to fix them with time

[orta]

Hi folks, I have a question - what do you think is better when it comes to making big updates to some docs already translated. For example in #873 I drastically rewrote the docs for the TSConfig esModuleInterop and allowSyntheticDefaultImports. This basically deprecates the Japanese and Portuguese translations.

When I do this should I:

1. Delete the translations and have them fall back to English?
2. Make an issue for replacing the specific files in a specific language?

I lean towards 1, but have reservations. So I'm asking people their opinions.

1, is a little rude! Someone worked hard on that translation, and deleting it sucks. However, deleting it does not force someone else to do work under any timeframe. The gap will show up in the internationalization issue for your language as something to pick up eventually.

I don't plan on doing this often (most of the English docs are solid) but I'd like to at least get a sense of whether this is the right idea if it comes up again.

[KingDarBoja]

I would opt for the second choice and have some sort of automated issue to keep track which files requires translation updates so translators don't get confused which file got already the new translation.

[orta]

Hrm, yeah, maybe I could add a outdated: "08/07/2020" to the yml front-matter on those files and then the issue script can pick it up and place it at the top of the issue.

[danilofuchs]

Perhaps it is an over engineered approach, but perhaps if the english content is newer than the translated content, a warning could be placed on top of the article, saying something like:

This documentation in Portuguese may be outdated. The original article was updated on 2020/08/07, but the last translation is from 2020/06/01. Maybe you can help us make it up to date! (Github Pinned Issue)

[khaosdoctor]

I like @KingDarBoja's idea, I think we can mix both of them. We could add an outdated label and also fallback these contents to the English Version.

[orta]

Interlinking my proposal for moving to a separate repo for translations, which should be happening Feb 2021 - #1480

[orta]

It's February, and it's happening: https://github.com/microsoft/TypeScript-Website-Localizations/

[orta]

This is done and shipped