New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add sample on how to localize in VS Code #21

Merged
merged 3 commits into from Nov 6, 2017

Conversation

Projects
None yet
5 participants
@vazexqi
Contributor

vazexqi commented Jul 10, 2017

What does this PR do?

As far as I can tell, there is not much documentation on how extension authors can localize their VS Code extensions. VS Code itself (and extensions that are bundled with it, are properly localized) but there are not many examples of how to do it (short of reading the source code). There have been several questions on this:

This is a small extension that shows several things:

  1. What you can localize (strings in package.json and strings in your .ts/.js files)
  2. How to localize them (create package.nls.{language}.json and the various .json file)
  3. How you can do so automatically using the vscode-nls and vscode-nls-dev packages.

What is not in the scope of this PR?

This PR does not talk about Transifex and different file formats for localization. The vscode-nls-dev module supports it but I intentionally left it out since the implementation seems very specific to the way Microsoft is doing it. This PR makes it simple by assuming that you have the required structure in the i18n folder (you either did it by hand or imported it using some other means)

It also tries to demystify a lot of the magic that vscode-nls is doing by suggesting manual but simpler ways for accomplishing the same thing.

Disclosure

Another reason I am doing this is also to learn how localization works in VS Code and also validate some of my assumptions on what is save to use (API stable). We are creating several extensions and localization is something that we have been asked to look into. Even if this PR is not accepted, comments on the assumptions in my code is appreciated so that we can understand what we should or should not rely on.

package.nls.json and the vscode-nls library for localization. For this sample,
it shows two commands: Hello and Bye in English and Japanese.
**Assumptions**

This comment has been minimized.

@vazexqi

vazexqi Jul 10, 2017

Contributor

Are these assumptions valid?

@vazexqi

vazexqi Jul 10, 2017

Contributor

Are these assumptions valid?

@dbaeumer

This comment has been minimized.

Show comment
Hide comment
@dbaeumer

dbaeumer Nov 3, 2017

Member

@vazexqi none of the files do have a copyright statement. Do you want to add some or can I add the standard MS one.

Member

dbaeumer commented Nov 3, 2017

@vazexqi none of the files do have a copyright statement. Do you want to add some or can I add the standard MS one.

@dbaeumer

This comment has been minimized.

Show comment
Hide comment
@dbaeumer

dbaeumer Nov 3, 2017

Member

@vazexqi I worked on the PR and made a couple of changes, mainly around structure and things that have changed in our thinking around nls in the meantime.

The demo.gif got outdated through that. Could you please generate a new one. The change I made are available here: https://github.com/Microsoft/vscode-extension-samples/tree/vazexqi-master

Member

dbaeumer commented Nov 3, 2017

@vazexqi I worked on the PR and made a couple of changes, mainly around structure and things that have changed in our thinking around nls in the meantime.

The demo.gif got outdated through that. Could you please generate a new one. The change I made are available here: https://github.com/Microsoft/vscode-extension-samples/tree/vazexqi-master

@vazexqi

This comment has been minimized.

Show comment
Hide comment
@vazexqi

vazexqi Nov 3, 2017

Contributor

@dbaeumer - Thanks for the review and changes.

  1. I'll add the standard Microsoft one of to all the .ts. files
/*---------------------------------------------------------
 * Copyright (C) Microsoft Corporation. All rights reserved.
 *--------------------------------------------------------*/
  1. I'll update the gif

I should be able to do this over the weekend and have an updated PR in by Monday.

Contributor

vazexqi commented Nov 3, 2017

@dbaeumer - Thanks for the review and changes.

  1. I'll add the standard Microsoft one of to all the .ts. files
/*---------------------------------------------------------
 * Copyright (C) Microsoft Corporation. All rights reserved.
 *--------------------------------------------------------*/
  1. I'll update the gif

I should be able to do this over the weekend and have an updated PR in by Monday.

@vazexqi vazexqi closed this Nov 6, 2017

@vazexqi vazexqi reopened this Nov 6, 2017

@vazexqi vazexqi closed this Nov 6, 2017

@vazexqi vazexqi reopened this Nov 6, 2017

@vazexqi

This comment has been minimized.

Show comment
Hide comment
@vazexqi

vazexqi Nov 6, 2017

Contributor

@dbaeumer I've rebased master of https://github.com/vazexqi/vscode-extension-samples onto the latest master of https://github.com/Microsoft/vscode-extension-samples and cherry-picked your changes over since I don't have access to push to vazexqi-master on this repo.

I've also regenerated the gif so that it shows using gulp package.

I noticed that you removed two files (i18n-sample/i18n/jpn/out/command/sayBye.i18n.json and i18n-sample/i18n/jpn/out/extension.i18n.json). This might have been because your .gitignore is too strict. If you don't have those files, then when you run gulp package you are going to see

[17:17:04] [i18n] Generating localized messages for 'jpn' resulted in the following problems:
[17:17:04] [i18n]
[17:17:04] [i18n] Message file jpn/out/extension.i18n.json not found. Missing messages: 1
[17:17:04] [i18n]
[17:17:04] [i18n]
[17:17:04] [i18n] Generating localized messages for 'jpn' resulted in the following problems:
[17:17:04] [i18n]
[17:17:04] [i18n] Message file jpn/out/command/sayBye.i18n.json not found. Missing messages: 1
[17:17:04] [i18n]
[17:17:04] [i18n]
[17:17:04] Finished 'internal-nls-compile' after 799 ms
[17:17:04] Starting 'add-i18n'...
[17:17:04] [i18n] Generating localized messages for 'jpn' resulted in the following problems:
[17:17:04] [i18n]
[17:17:04] [i18n] Message file jpn/package.i18n.json not found. Missing messages: 2
[17:17:04] [i18n]
[17:17:04] [i18n]

I've added them back in.

Contributor

vazexqi commented Nov 6, 2017

@dbaeumer I've rebased master of https://github.com/vazexqi/vscode-extension-samples onto the latest master of https://github.com/Microsoft/vscode-extension-samples and cherry-picked your changes over since I don't have access to push to vazexqi-master on this repo.

I've also regenerated the gif so that it shows using gulp package.

I noticed that you removed two files (i18n-sample/i18n/jpn/out/command/sayBye.i18n.json and i18n-sample/i18n/jpn/out/extension.i18n.json). This might have been because your .gitignore is too strict. If you don't have those files, then when you run gulp package you are going to see

[17:17:04] [i18n] Generating localized messages for 'jpn' resulted in the following problems:
[17:17:04] [i18n]
[17:17:04] [i18n] Message file jpn/out/extension.i18n.json not found. Missing messages: 1
[17:17:04] [i18n]
[17:17:04] [i18n]
[17:17:04] [i18n] Generating localized messages for 'jpn' resulted in the following problems:
[17:17:04] [i18n]
[17:17:04] [i18n] Message file jpn/out/command/sayBye.i18n.json not found. Missing messages: 1
[17:17:04] [i18n]
[17:17:04] [i18n]
[17:17:04] Finished 'internal-nls-compile' after 799 ms
[17:17:04] Starting 'add-i18n'...
[17:17:04] [i18n] Generating localized messages for 'jpn' resulted in the following problems:
[17:17:04] [i18n]
[17:17:04] [i18n] Message file jpn/package.i18n.json not found. Missing messages: 2
[17:17:04] [i18n]
[17:17:04] [i18n]

I've added them back in.

@dbaeumer

This comment has been minimized.

Show comment
Hide comment
@dbaeumer

dbaeumer Nov 6, 2017

Member

So, that was my mistake. I will tweak the git ignore and add the files back.

Member

dbaeumer commented Nov 6, 2017

So, that was my mistake. I will tweak the git ignore and add the files back.

@dbaeumer dbaeumer merged commit 9ec4b5d into Microsoft:master Nov 6, 2017

1 check passed

license/cla All CLA requirements met.
Details
@dbaeumer

This comment has been minimized.

Show comment
Hide comment
@dbaeumer

dbaeumer Nov 6, 2017

Member

Thanks again. Merge into master

Member

dbaeumer commented Nov 6, 2017

Thanks again. Merge into master

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment