Repository navigation
Website Internationalization Roadmap #100
Description
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
-
Join the TypeScript Discord - come say hi the
ts-web-translate -
Clone the repo. The work will happen on the
v2branch. 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-
Look below to see the sections, then come back up here
-
Read this PR to see an example of adding a language: Create an example PR which shows how to add a language #181
-
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.
Activity
[-]Exploration: Playground examples in another language[/-][+]Website Internationalization mega-thread[/+]orta commentedon Nov 13, 2019
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
[-]Website Internationalization mega-thread[/-][+]Website Internationalization Roadmap[/+]orta commentedon Jan 2, 2020
#163 adds the ability to create and present internationalized playground samples
glaucia86 commentedon Jan 14, 2020
Orta Therox (@orta) hi! I was talking to Daniel, that you can count on me about to translate this pages to Portuguese. :)
orta commentedon Jan 15, 2020
Woooo!
Naturalclar commentedon Jan 16, 2020
Orta Therox (@orta)
Hello! I can help translating the website into Japanese :)
evanSe commentedon Feb 5, 2020
Hey Orta Therox (@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 commentedon Feb 5, 2020
Hi Evan Seaward (@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
ifunction in the React componenti("key")to get the textDocumentation is a solid place to start, think about bits which would change between languages (subheadings probably) vs which would never "React", "Angular" etc
orta commentedon Jul 20, 2020
#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 commentedon Jul 23, 2020
My general recommendations for reviewing localization are:
orta commentedon Aug 7, 2020
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
esModuleInteropandallowSyntheticDefaultImports. This basically deprecates the Japanese and Portuguese translations.When I do this should I:
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 commentedon Aug 7, 2020
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 commentedon Aug 7, 2020
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 commentedon Aug 7, 2020
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:
khaosdoctor commentedon Aug 8, 2020
I like KingDarBoja (@KingDarBoja)'s idea, I think we can mix both of them. We could add an
outdatedlabel and also fallback these contents to the English Version.orta commentedon Jan 25, 2021
Interlinking my proposal for moving to a separate repo for translations, which should be happening Feb 2021 - #1480
orta commentedon Feb 1, 2021
It's February, and it's happening: https://github.com/microsoft/TypeScript-Website-Localizations/
orta commentedon Jan 12, 2022
This is done and shipped