Localize rest of strings

[TylerLeonhardt]

Now that #220 is in, localizing the rest of the strings should be straightforward.

Step 1: localize calls

For every file that contains a user facing string, you'll do the following:

• include the import (order doesn't matter, just needs to happen after that setup import from above):

import * as nls from 'vscode-nls';

You must use this import format and not import { ... } from 'vscode-nls';. Please see: microsoft/vscode-nls-dev#36

• Load the messages (this can go right after your imports):

const localize = nls.loadMessageBundle();

• Replace all user-facing strings with a call to localize(). Here are some examples:

// simple
localize('some unique-to-this-file id', 'User facing string to translate');

// parameters
localize('some unique-to-this-file id', 'User facing string to {0}', translate);

// comments with a way to ensure something isn't translated
localize({
  key: 'some unique-to-this-file id',
  comment: [
    // This is magic localization syntax to enforce that this part of the string must not be translated.
    "{Locked='](command:donttranslateme)'}",
    "Do not translate the 'command:*' part inside of the '(..)'. It is an internal command syntax for VS Code"
  ]
}, '[translate me](command:donttranslateme)');

NOTE: It's ok to be iterative here. Convert a few strings over to use localize, then in a follow up PR, do more.

Additional context around the localize call

Let's take this example:

localize(
  {
    key: 'some unique-to-this-file id',
    comment: [
      // This is magic localization syntax to enforce that this part of the string must not be translated.
      "{Locked='do not translate me'}",
      "Do not translate the 'do not translate me' part"
    ]
  },
  'translate me but do not translate me but also here is a parameter: {0}',
  'foo'
);

The first parameter is either just a string which represents the key or an object that has a key and a comment property.

The key isn't really important, it's just an identifier of the string. You can put whatever you want there, it just has to be unique to the TS file that contains the string. Yes, this means that you could reuse the same key across different TS files so if that makes sense for you, don't be afraid to do that.

The comment section is a way to manipulate how the string is translated. You can either use the special {Locked=''} syntax which is called "functional commenting" (docs on functional commenting), or you can use a normal comment which will be shown to the translator responsible for translating the string. Using both is ideal because the functional commenting also applies to the Pseudo Language generation which a human is not involved with and the normal comments help describe our code better.

The next thing we have is the actual literal string that will be sent to translators. Let me be clear. The EXACT string that a translator will see is translate me but do not translate me but also here is a parameter: {0} (even with the {0} part). This is because our strings are sent over at build time - not runtime. It's important that this parameter is completely static (no concatenation, no interpolation, nothing) because we scan the TS for the strings and do not run the code at all.

The final parameter(s) of our call are the segments of the string that will be filled in at runtime. When VS Code runs, it will take the value of these parameters and replace the {0} {1} {2} etc syntax with the respective parameters passed in after the string to be translated.

Step 2: package.nls.json

The other strings that we need to translate are found in your package.json. You'll have plenty of strings in the contributes section. These strings can be moved over to a package.nls.json file and look like so:

{
  "displayName": "Remote Repositories",
  "description": "Remotely browse and edit git repositories",
  "colors.added": "Color for added resources",
  "colors.modified": "Color for modified resources",
  "colors.deleted": "Color for deleted resources",
  "colors.conflict": "Color for resources with conflicts",
  "colors.incomingAdded": "Color for incoming added resources",
  "colors.incomingModified": "Color for incoming modified resources",
  "colors.incomingDeleted": "Color for incoming deleted resources",
  // NOTICE THE LONG FORM WITH COMMENTS:
  "viewsWelcome.explorer": {
    "message":"You can remotely open a repository or pull request without cloning.\n[Open Remote Repository](command:remoteHub.openRepository)",
    "comment": [
      "{Locked='](command:remoteHub.openRepository)'}",
      "Do not translate what's inside of the '(..)'. It is an internal command syntax for VS Code"
    ]
  },
  // etc
}

The keys of these strings are then referenced in the package.json with % around them like so:

{
  "name": "remote-repositories",
  "private": true,
  "displayName": "%displayName%",
  "description": "%description%",
  // etc
}

NOTE: It's ok to be iterative here. Convert a few strings over to use package.nls.json, then in a follow up PR, do more.

[andreamah]

verif steps:

• download newest live preview:
  ms-vscode.live-server.0.2.14.zip
• try translating to something like Czech