electron/i18n

🌍 The home of Electron's translated documentation

electron-i18n

THIS PROJECT IS DEPRECATED The i18n efforts continue happening in Crowdin but the sync is done directly on electron/electronjs.org-new.

i18n's Issues

Removes the translations made by machine translations in Spanish

Removes the translations made by machine translations in Spanish

Translation made by glotbot used automatic machine translation (#6), 70% need to be retranslated.

Make sure Chinese Traditional and Simplified have the proper native labels

Looks like the Chinese native language names are the same here:

@vanessayuenn @zcbenz is one of them wrong? Which one?

We are currently using the locale-code module to get this info, and this wouldn't be the first time that's not exactly right:

https://github.com/electron/electron-i18n/blob/f3cc99dfb6ef27624a693834042fae98904af36b/lib/locales.js#L23

Best long-term answer might be to swap out locale-code with a more accurate module.

What happens to ignored spellcheck terms?

I just ignored "GitHub"

Will this be ignored across all languages?

Do these ignored words get added to a list somewhere that can be reviewed/edited?

Surface improvements to tutorials on the website more quickly

Problem

The website currently displays docs from the latest stable version of Electron. The stable version doesn't change very often, and sometimes there are weeks of beta versions before the next stable bump.

While it makes sense for the website's API documentation to strictly match the current stable version of Electron, the tutorial content found in docs/tutorial is generally not Electron-version-specific.

Currently we fetch all docs from latest:

Files	Source Commitish
/docs/**/*.md	electron@latest
locale.yml	electron.atom.io#master

Instead, I propose that we fetch docs/tutorial/** straight from Electron's master branch:

Files	Source Commitish
/docs/api/**/*.md	electron@latest
/docs/development/**/*.md	electron@latest
/docs/tutorial/**/*.md	electron#master
locale.yml	electron.atom.io#master

cc @leo, whose eagerness to see electron/electron#10251 deployed on the website prompted this idea.

Try out Google's machine translation service

In #6, we gave Microsoft's machine translation service a try. But as @vaartis suggested in that thread, perhaps we should also try out Google's service, which is supported by Crowdin.

Here's some info that @alebourne gathered about Google's service:

In March 2017, Google has released the commercial version of their translation API that with Neural Translation Memory. This brings their offering on par to Microsoft already existing support of NMT.

The Neural Machine Translation arms race is on!

The Neural Translation model is now used when signing up for the Premium edition as a default, and if a language pair is not available, then the Phrase based (older style machine translation) is used.
To quote the Google website (https://cloud.google.com/translate/docs/premium):

Instead, the premium features of the Google Cloud Translation API have been made generally available in the Standard Edition. All users have access to the robust translation features available using the Neural Machine Translation (NMT) model, as well as the capabilities of the Phrase-Based Machine Translation (PBMT) model. There is no difference in pricing between the standard, PBMT model, and the NMT model.

The current list of languages that support Neural Machine Translaiton is here:
https://cloud.google.com/translate/docs/languages#languages-nmt

mention XTM, Smartling, Memsource

Point collect script at website's master branch

data/locale.yml is currently fetch from the neo branch. When electron/electronjs.org-old#758 lands we'll need to update script/collect.js

Setting up GitHub integration using @glotbot account

I created the @glotbot user on GitHub to serve as a shareable account that any GitHub employee can use to log in and administer the crowdin.com/project/electron project. Because the @glotbot user has limited privileges and is not an owner of the github or electron org, this will also reduce the surface area that would be at risk if Crowdin were compromised and a bad actor gained access to @GLobot's auth token.

I added @glotbot as a collaborator on this repo with write privileges:

But when I try to set up the GitHub integration in Crowdin, the repo is not listed:

I was previously generating a token using my @zeke account and using that, but that defeats the purpose of the @glotbot user.

Using Translation Memory suggestions

is there a way to apply translations from the Translation Memory (TM) in bulk? Or to have them applied automatically?

Electron Documentation `README` is inaccurately titled FAQ

https://electronjs.org/docs/README

can we have hi-IN translations started?

so I was looking for Hindi (India) translations but couldn't find any. if possible, could someone add/authorize to add Hindi i18n translations on crowdin

thanks
sambhav

Character encoding issues in translated YML files

The English file doesn't have issues:

https://github.com/electron/electron-i18n/blob/a3256e88cacf589a82427c25ea274801740ffce1/content/en/api/api-descriptions.yml#L715-L720

The Czech file does:

https://github.com/electron/electron-i18n/blob/a3256e88cacf589a82427c25ea274801740ffce1/content/cs-CZ/api/api-descriptions.yml#L505-L509

My editor is displaying some unrecognized characters:

And here's the error the js-yaml parser is throwing:

  1) electron-i18n translated content preserves YAML formatting of API descriptions:
     end of the stream or a document separator is expected at line 505, column 18:
                     
                     ^
  Error
      at generateError (node_modules/js-yaml/lib/js-yaml/loader.js:162:10)
      at throwError (node_modules/js-yaml/lib/js-yaml/loader.js:168:9)
      at readDocument (node_modules/js-yaml/lib/js-yaml/loader.js:1513:5)
      at loadDocuments (node_modules/js-yaml/lib/js-yaml/loader.js:1549:5)
      at load (node_modules/js-yaml/lib/js-yaml/loader.js:1566:19)
      at Object.safeLoad (node_modules/js-yaml/lib/js-yaml/loader.js:1584:10)
      at getKeys (test/index.js:39:26)
      at locales.forEach.locale (test/index.js:50:42)
      at Array.forEach (native)
      at Context.it (test/index.js:48:15)

String should not be separated (content/en-US/website/locale.yml)

https://github.com/electron/electron-i18n/blob/c5b556077a82c7d611159b05df92ab8927f86dc3/content/en-US/website/locale.yml#L200
Current string in "search" is separated but this makes translations unnatural. (Some languages such as Japanese have different word order from English's one.)
It should be like below.

search:
  description: Find Electron resources from <a href="/search/docs">documentation</a>, <a href="/search/npmPackages">npm packages</a> and <a href="/search/repos">GitHub repos</a>.

Code formatting failed in Crowdin

Something has affected the development/build-instructions-linux.md

(https://electronjs.org/docs/development/build-instructions-linux)

• https://crowdin.com/translate/electron/all/en-ptbr#q=bash+%24
• https://crowdin.com/translate/electron/all/en-fr#q=bash+%24
• ... all

Abort API docs collection if latest version already exists

After pinging npm to find the latest stable version of Electron, the version should be checked against what already exists in the repository. If it's the same version, the docs download process should abort.

When we implement #128, we'll want to make sure that tutorials from the master are still collected, regardless of whether i18n's API docs are already up to date.

cc @vanessayuenn

Generate URLs for files on Crowdin so we can link to them from the website

From Andriy at Crowdin:

You may try to use Project Details endpoint:
https://support.crowdin.com/api/info/
? it dispays information about paths and files ID

Response sample:

    <item>
    <node_type>directory</node_type>
    <id>1</id>
    <name>test</name>
    <files>
      <item>
        <node_type>file</node_type>
        <id>2</id>
        <name>market-info.txt</name>
        <created>2017-05-19T13:08:13+0000</created>
        <last_updated>2017-05-20T18:02:13+0000</last_updated>
        <last_accessed>2017-05-21T09:10:48+0000</last_accessed>
        <last_revision>1</last_revision>
      </item>

It means, there is a directory named "a" containing file named "market-info.txt" and its ID is 2

The API supports JSON responses too, so we can do something like this:

const url = `https://api.crowdin.com/api/project/electron/info?key=${process.env.CROWDIN_KEY}&json`

See script/stats.js for prior art.

idea: associate github handles with crowdin accounts

Would be cool if we could automatically cc the github handles of all people that contributed translations in a given PR.

Continually re-apply existing translations from Translation Memory

Why did the Chinese translation progress on the Crowdin rollback? The progress from 29% to 25% and lost some translation?

like this file
with pull#132

Remove 'Class: ' prefix from titles in all languages

We are already doing this:

$('h2').first().text().replace('Class: ', '')

but folks are translating the Class part, and it's sneaking through into the parsed title property.

Try automatic machine translation

Crowdin can automatically apply machine translation to new content. This could be a big time-saver.

In order to use this, we'll need to add a machine translation API key to our Crowdin account from Google or Microsoft (or Yandex?)

https://support.crowdin.com/advanced-workflows/#accessing-the-workflows-feature

cc @alebourne

always spell it "YAML"

for consistency

Removed source files are still present in localized contents

Crowdin's synchronization does not detect removed/renamed files, so we'll have to figure out a way to handle that. This is currently blocking #222.

Saudade

@alebourne @pedro @zenorocha do you know this word? and do you like this definition of it?

Translate raw markdown API docs instead of YML API descriptions

Every Electron API has parts of its documentation that should remain in English. Let's look at an example:

#### `win.setAspectRatio(aspectRatio[, extraSize])` _macOS_

* `aspectRatio` Float - The aspect ratio to maintain for some portion of the
content view.
* `extraSize` [Size](structures/size.md) - The extra size not to be included while
maintaining the aspect ratio.

This will make a window maintain an aspect ratio. The extra size allows a
developer to have space, specified in pixels, not included within the aspect
ratio calculations. This API already takes into account the difference between a
window's size and its content size.

In the above example, the following things should remain untouched:

• heading level: ####
• method name and signature: win.setAspectRatio(aspectRatio[, extraSize])
• operating System: macOS
• argument list bullets: *
• argument names: aspectRatio and extraSize
• argument types: Float and Size

The only things that should be translated here are the descriptions, both for the arguments as well as the method itself:

• The aspect ratio to maintain for some portion of the content view.
• The extra size not to be included while maintaining the aspect ratio.
• This will make a window maintain an aspect ratio. ...

The Current Approach

In an effort to reduce the likelihood of translators changing content that should not be changed, I extracted all descriptions into a YML file. Here's an excerpt:

app.methods.hide.description: Hides all application windows without minimizing them.
app.methods.show.description: >-
  Shows application windows after they were hidden. Does not automatically focus
  them.
app.methods.getAppPath.returns.description: The current application directory.
app.methods.getPath.description: 'You can request the following paths by the name:'
app.methods.getPath.returns.description: >-
  A path to a special directory or file associated with name. On failure an
  Error is thrown.

This seemed like a good approach for a few reasons:

• no way for translators to edit content that shouldn't be edited
• descriptions are structured and can therefore be used to create a localized structured API docs data. This could then be used to make localized typescript annotations, snazzier localized API docs on the website, etc.

The Problem with the Existing Approach

The YAMLized descriptions has proven to be a bit confusing for translators so far. It seems that in some cases it's difficult to know how to translate a description without the surrounding context.

Here's an example of a contributor being confused #58

An Alternative Approach

I'm thinking maybe we should scrap this api-descriptions.yml idea in favor of pulling in all the raw markdown files from electron/electron/tree/master/docs/api.

This might be a better approach for a few reasons:

• Translators would always have the full context when translating API docs.
• Translators would have the opportunity to learn more about Electron's API in general as they go.
• The resulting content in the electron-i18n repo would stand on its own as a useable form of translated documentation. git clone https://github.com/electron/electron-i18n for an offline copy of Electron's documentation in every language.

To avoid the problem of translators changing content that should not be changed, we could enforce this at the GitHub pull-request level by running electron-docs-linter and electron-typescript-definitions as part of the existing test suite that runs on Travis.

Thoughts?

Curious to hear if people have feedback on this idea. It's not a lot of work to make this change on my end, but I first want to make sure that this is actually closer to what folks want and expect when translating Electron's API docs.

Crowdin is converting YAML string lines into an array

explore.description is a single string in the source English:

https://github.com/electron/electron-i18n/blob/0dd81e79da5e1090b379facc637451e4ec071615/content/en-US/website/locale.yml#L54-L60

But it ends up as an array in the translated files:

https://github.com/electron/electron-i18n/blob/0dd81e79da5e1090b379facc637451e4ec071615/content/fr-FR/website/locale.yml#L35-L39

There are other multi-line strings in the source file that don't end up as arrays.

Test that translated files are congruent with source files

The first crowdin pull-request is coming together nicely. Let's add some tests to verify that Crowdin is naming the translated files as expected, and that the structure of the YML files is consistent in all locales.

remove acrolinx from readme

Use probot to steer folks to Crowdin

In #33, a kind user opened a pull request with translated content. Unfortunately this repo is not the source of translated content, but rather the destination. When this happens we should help guide the person to make edits on Crowdin instead.

This sounds like a job for probot.

cc @bkeepers @lee-dohm

Prefix Crowdin commit messages (or PR title)

We want Crowdin-generated PRs to automatically trigger a release when they're merged. We can do this by either configuring the prefix, e.g. New translations cookie.md (Hindi) becaomes feat: New translations cookie.md (Hindi), or perhaps there's a way to customize the PR title in Crowdin's config.

Highlight "Project of the Week" apps

We've conducted interviews with developers of several apps like Beaker and Webtorrent, and bogged about them.

When viewing an app that's been featured, some kind of "read the blog post" message should be displayed on the app page.

Conversely, when reading a POTW blog post, we should include a link to the app's Electron page.

Invite existing Electron translators to participate

We haven't made much noise about this new i18n project yet. 🙊

So far, only people paying extra-close attention have noticed and jumped in. As we get closer to being ready to expand this effort, we should reach out to the 100+ people who have already submitted translation PRs to electron/electron.

The electron/electron-translators project exists to collect the github usernames of those folks, so we can reach out to them.

The node project creates a GitHub team for each locale:

...we could copy this model if necessary.

rename repo to i18n

The Node.js internationalization repo is called https://github.com/nodejs/i18n (without a prefix) and @vanessayuenn and I are feeling a little jealous.

Would anyone object to us renaming this repo to electron/i18n? (Of course GitHub will redirect if anyone visits the old electron-electron-i18n URL.

Prioritizing languages for translation

Here's a summary of languages that have existing translated content in the electron repo:

	Locale	Translators	Language Name
🇨🇳	zh-CN	56	Chinese Simplified
🇹🇼	zh-TW	16	Chinese Traditional
🇧🇷	pt-BR	24	Portuguese, Brazil
🇪🇸	es	20	Spanish
🇰🇷	ko-KR	19	Korean
🇯🇵	jp	17	Japanese
🇷🇺	ru-RU	11	Russian
🇫🇷	fr-FR	6	French
🇹🇭	th-TH	4	Thai
🇳🇱	nl	3	Dutch
🇹🇷	tr-TR	3	Turkish
🇮🇩	id	2	Indonesian
🇺🇦	uk-UA	2	Ukrainian
🇨🇿	cz	1	Czech
🇮🇹	it-IT	1	Italian

`translateUrl` for some of the locales are incorrect

It looks like if the language codes contain dashes, the translateUrl should have them omitted, with the exception of Spanish. For example, https://crowdin.com/translate/electron/92/en-zh-CN should actually be https://crowdin.com/translate/electron/92/en-zhcn.

The language codes with dashes are es-ES, zh-CN, zh-TW, pt-BR.

This is sort of blocking electron/electronjs.org-old#975.

Litost

@tonyganch @cifratila does this definition do the word justice?

Delete old files

Looking at this with Russian as the current language, I see some non-translate-able articles -- they are not listed here:

• https://electronjs.org/docs/tutorial/debugging-main-process-node-inspector
• https://electronjs.org/docs/development/upgrading-chrome

Looks like they are just old/legacy.
Need to delete corresponding files in here.

miss word in notification-action.md

one word is miss. content/docs/api/structures/notification-action.md
incomptible -> incompatible
thanks

Seeking translator feedback

Hello @electron/i18n folks! 👋

We put together a quick survey to collect feedback from Electron's translator community.

Our goals:

✅ Correlate GitHub usernames to Crowdin usernames so we can acknowledge contributions.

✅ Learn what motivates you to participate

✅ Find out how we can improve the translation process

If you haven't filled it out already, please do! https://goo.gl/forms/b46sjdcHmlpV0GKT2

And if you want to help spread the word, please retweet: https://twitter.com/electronjs/status/964644949298827264

Export GitHub source URL in doc objects

When viewing a doc on the Electron website, we should have a way to link to its source on GitHub.

e.g. /docs/api/app -> https://github.com/electron/electron/tree/master/docs/api/app.md

Can I pull requests here?

I found wrong docs in electron-i18n.
So I see the pull requests, It merged only by zeke and glotbot.

Account for arrays when generating api-descriptions.yml

Some descriptions are deeply nested inside arrays, which means they can't be addressed using a foo.bar.baz style key.

Example:

> 
[ { name: 'options',
    type: 'Object',
    collection: false,
    required: false,
    properties: 
     [ [Object],
       [Object],
       [Object],
       ....
] } ]

So we need something like apis.BrowserWindow.constructorMethod.parameters.0.options.properties

I think flat may have an option for this.

Conversation with Crowdin

We'll be meeting with some folks at Crowdin later this week to share feedback on our experience so far, and to learn how to use Crowdin more effectively on the Electron project.

Question: How can we prevent translation of certain content?

The Indonesian translations currently have a lot of problems. A screenshot illustrates many of them:

Question: How do we settle on a given translation?

We're starting to see multiple translation suggestions. How should we handle this? For example, can we apply a voting system that will take effect automatically without intervention?

Question: How can we communicate with a given language community?

We want to reach out to our Indonesian translators to collectively seek out solutions to the problem of mistranslated content (and also to thank them for their help!). Is there a way to carry out a language-scoped conversation on Crowdin?

Question: What is the Context Editor?

https://crowdin.com/translate/electron/9/en-ar#267:ac:86

Feature request: Easier deep linking to Translation pages

See https://github.com/zeke/get-crowdin-file-ids

Imagine you're serving up some Crowdin-translated content on your website and you want to add a link to each page that lets translators jump right into translating that content on the Crowdin site. Unfortunately, the URLs on Crowdin's translation pages are a bit cryptic:

https://crowdin.com/translate/electron/56/en-fr

Here 56 refers to Crowdin's internal id property for a given file.

It would be great if Crowdin accepted URLs that contained target language and target filename as parameters and redirected to the appropriate URL. For example:

https://crowdin.com/translate/electron/go?language=en-FR&filenaname=foo.md

Feature request: Delete old files

See #198

Please check crowdin comment

I left a comment to fix some typo errors in english source files but there are no reply for that and it has not changed yet.

Would I report those of issue on github issue instead of crowdin comment?

tutorial/accessibility.md needs to be updated?

Crowdin eng source needs to be updated for tutorial/accessibility.md.

Read on for a summary of the tools.

It is the same contents with https://github.com/electron/electron/blob/master/docs/tutorial/accessibility.md.

But it looks different in https://electronjs.org/docs/tutorial/accessibility:

Read on for a summary of the tools or checkout our accessibility documentation for more information.

I don't have any idea where these additional sentences came form.
If it is correct on the website document version, I'll create PR for that.

In the case of quick-start.md, I don't know how to handle it.

https://github.com/electron/electron-i18n/blob/master/content/en-US/docs/tutorial/quick-start.md
https://github.com/electron/electron/blob/master/docs/tutorial/quick-start.md
https://electronjs.org/docs/tutorial/quick-start

Is it sync issue? or is it normal just representing contents with merging some contents dynamically on website?

Translating API docs without context is confusing

https://crowdin.com/project/electron/
in this website , content/en/api is empty, how can i create a new file

Build a glossary

Now that we're including Electron's markdown API docs in the source content, there are pieces of those docs that we don't want translated. Examples include api names like BrowserWindow, method names like win.isFocused, data types like String and Array, etc.

Here's an example of what we don't want:

We can use Crowdin's glossaries to solve this problem. From Crowdin support:

Glossaries are created for the clarification of the specific terms used in the project. Terms are displayed as the underlined words in the Editor.

They get highlighted while hovering on them so that the project participants can see the description.

In the description of the term you can specify that String should not be translated because it's a data type.

You may upload/download glossaries via API if you have any existing ones. Here more information:

https://support.crowdin.com/api/upload-glossary/
https://support.crowdin.com/api/download-glossary/

Write an introductory guide for translators

We have a contributing.md but it doesn't say much about the actual translation process. Let's add to it and use it as a starting point where we can point new translators.

A few things to cover:

• All translation happens on Crowdin (do not open translation PRs on the i18n repo)
• If you find typos in the source content, open a PR on electron/electron or electron/electronjs.org
• Do not translate javascript keywords, electron class names, module names, method names, return types, etc.
• Pay attention to the glossary terms (assuming #82 has been implemented)

Rewrite image src attributes to be fully qualified CDN URLs

electron/electron#11032 just shipped, and includes a bunch of image files in /docs/images. In retrospect it seems like the fully-qualified URL approach may not scale without a bunch of "education" and linting. So we need to somehow carry these images over from electron/electron to electron/electronjs.org. The easiest way to do this is probably to just update electron-i18n to also fetch images in the collect script, then ensure that the images are included in the published npm package (i.e. not npmignored).

If we take this route, we'll need to update the build process to rewrite all relative image URLs to refer to something like node_modules/content/en-US/docs/images/foo.png

cc @groundwater @codebytere

[Suggestion] limited proofreader role of specific language

I find out there are broad proofreader role in electron crowdin project.
There are two ways to give a proofreader permission to users on Crowdin.

• changing translator role to proofreader.
• add proofreader permission for specific language(recommended) with translator role

In the current setting(https://crowdin.com/project/electron/translators), every proofreader can handle every languages. Actually, it doesn't make sense because it is impossible to know every languages. So, I think that setting up limited proofreader role per language based on what they have translated would help to make better translation quality.

Fix Travis CI for Pull Requests from forked repos

#162 is failing because Travis does not expose its env vars to forks

MissingEnvVarsError: The following variables are defined in .env.example but are not defined in the environment: GH_TOKEN, CROWDIN_KEY.

Let's revamp the test suite to not rely on these env vars.