Conflicting documentation

[deakjahn]

Dear me. :-) I know it's not the best place to ask but how do you use it? Documentation seems to be very contradicting, some suggest to use the vscode/l10n dependency, others say it's built-in already if you only want to use in the main extension. package.nls.json gets picked up all right but I simply can't make the bundle.l10n.json work.

Without the dependency, trying to use vscode.l10n.t() gives an error of Property 'l10n' does not exist on type 'typeof import("vscode").

If I do depend on the package, then I can import:

import { t } from "@vscode/l10n";

And it looks like it might work but then comes a very nasty surprise: is it real that, in the bundle files, I have to use the English original as a key? Can't I use a key like in the package level? Eg:

"extension.key1.text": "first text",
"extension.key2.text": "second text",
"extension.key3.text": "third text",

Really? I hope not because this would be rather problematic. After all, the same original won't always be translated to the same localized string. There are homonyms in English. There might be situations when the same expression has to be spelled, cased or translated differently, depending on context. Tell me I misunderstood something...

[TylerLeonhardt]

@deakjahn whether to use the built-in API or @vscode/l10n depends on where the code is running.

If you have access to the built-in API (meaning your code is running in the main extension host process) then you use the built-in API.

If you are running code outside of that in a separate process that you would also like to localize, you can use @vscode/l10n. This is a more advanced scenario but is needed for things like language servers.

[TylerLeonhardt]

With that said,

import { t } from "@vscode/l10n";

I don't think I support this form of import. For now, this has to be:

import * as l10n from "@vscode/l10n";

I'm working on catching these edge cases.

Note this should work (if you're running in the extension host):

import { l10n } from "vscode";

[deakjahn]

Sorry, but there's the rub. That's why I wrote in the first place. :-)

import { l10n } from "vscode";

doesn't work (neither does the variation with asterisk and referencing it by name). Red squiggly under l10n and the error message Module "vscode" has no exported member 'l10n'. I only started to experiment with the dependece just because it didn't work the other way...

I'm in VS Code 1.73.1, it says no update is available, it's fresh.

By the way: "I don't think I support this form of import. For now, this has to be:". You do. It compiles and, actually, it's much nicer to only need to type t() without any prefix.

[deakjahn]

As to the other issue, couldn't that be solved so that we can have our cake and eat it, too? Considering that it would also solve the other issue of not yet thinking about people who need something else than English as their neutral, fallback language?

Basically, what I would suggest is to make use of bundle.l10n.json if present, and no change if it isn't. Right now, we're expected to provide:

• no file for the neutral language, the string comes directly from the t() parameter;
• bundle.l10n.locale.json for any other language, the string comes keyed by the t() parameter;

Adding bundle.l10n.json would simply mean that the neutral language is also looked up, keyed by the t() parameter

• bundle.l10n.json for the neutral language, the string comes keyed by the t() parameter;
• bundle.l10n.locale.json for any other language, the string comes keyed by the t() parameter;

This second would solve the remaining problems. First, we would be free to use whatever key we like, be it a real key or the original string. Second, it would also solve the fallback language problem, the neutral bundle could contain any language, not only English. Those who want to use a different language and localize to English instead of the other way around would simply provide a bundle.l10n.en.json file.

Besides, all those current and future users who don't use such a neutral bundle would receive the current treatment without any breaking change.

[TylerLeonhardt]

What engine version are you using in the package.json? What @types/vscode version are you using in the package.json?

[TylerLeonhardt]

By the way: "I don't think I support this form of import. For now, this has to be:". You do. It compiles and, actually, it's much nicer to only need to type t() without any prefix.

I know it works at runtime but when you use npx @vscode/l10n-dev export -o l10n ./src does that include your t(..) strings? That I'm not sure about.

[deakjahn]

I have:

"engines": {
  "vscode": "^1.52.0"
},

"@types/vscode": "~1.52.0",

I never thought that I had to keep track of new versions myself, none of the other platforms I develop on make me do so. Do I really need to?

Fair enough, I don't know about extracting t(), I didn't use that.

[deakjahn]

I checked out a couple of FOSS extensions from the marketplace and they all seem to do the same, tilde notation and 1.52. Now I tried to change it to caret. npm upgrade did fetch 1.73.0 but the whole system ground to a halt. Vscode stopped working altogether: Cannot find module 'vscode' or its corresponding type declarations.

I went back to 1.52, at least it works now, except for the localization. :-)

[TylerLeonhardt]

"engines": {
  "vscode": "^1.73.0"
},

"@types/vscode": "1.73.0",

Change to this, then run npm install.

This is saying "I work with VS Code 1.73.0 and higher and only use API in those versions."

If you have 1.53, then you work with VS Code 1.53 and higher. 1.53 doesn't have the localization API so you don't get completions for it.

[TylerLeonhardt]

I'm going to update the docs to include this engine.

[deakjahn]

Yep, that did the trick, thanks.

If we could only convice you to support bundle.l10n.json directly, as mentioned above, both to be able to use keys and to support non-English default scenarios, we would be really happy bunnies... :-)

[TylerLeonhardt]

PR out to update README... let's talk "default language" in the issue dedicated to it microsoft/vscode#168127