Developer Reference

Developer Reference

Use this page for cross-cutting development references that do not fit setup, contribution policy, or test execution workflows.

Contents

• Localization (v2)
• Localization (v3 and next)
• Logging
• Keybinding reference chart
• Related developer references

Localization (v2)

All localized strings must be string literals. Avoid variables and template literals in the localization call argument.

Adding strings

1. Create a key name for the string.
2. Localize either package.json values or TypeScript code.

For package.json strings:

• Replace literal text with %key%, for example "This is a string" becomes "%exampleProperty.exDescription%".
• Add the key/value to package.nls.json.

For TypeScript strings:

• Ensure vscode-nls is imported:

import * as nls from "vscode-nls";

• Set up localization:

nls.config({ messageFormat: nls.MessageFormat.bundle, bundleFormat: nls.BundleFormat.standalone })();
const localize: nls.LocalizeFunc = nls.loadMessageBundle();

• Wrap strings with localize("key", "string").

After adding/updating/removing strings, run:

yarn workspace vscode-extension-for-zowe package

This updates sample files in i18n.

Adding a new language

1. In root i18n, duplicate sample and rename to an ISO-639-3 language code.
2. Download translated .json files from Zanata and replace files in your new language folder.
3. Update gulpfile.js languages array with { folderName: '<ISO-639-3-Code>', id: '<vscode-locale-id>' }.
4. Install the target VS Code language pack and package again to validate output.

Donating translations

1. Sign up at Zanata.
2. Email maintainers with subject ZANATA TRANSLATOR REQUEST and include:
   • Zanata username
   • Language(s)
   • Affiliation with Zowe
3. See Zanata translator guide for details.

Localization (v3 and next)

Localized strings can use placeholders like {0}, {1} with values supplied at call time.

Adding a new language

1. Navigate to packages/zowe-explorer/l10n.
2. Create package.nls.<my-language>.json.
3. Add translated content based on package.nls.json.

For more information, see the vscode-l10n documentation.

Adding strings

1. Create a key for your string.
2. Update package.json and/or TypeScript as needed.

For package.json strings, use %key% and update package.nls.json.

In TypeScript, one localization approach is:

vscode.l10n.t({
  message: "My {0} localized string",
  args: ["First"],
  comments: ["The amount of times a string was localized"]
});

After adding/updating/removing strings, run:

pnpm --filter vscode-extension-for-zowe vscode:prepublish

This updates sample files under l10n.

Donating translations

Use the same Zanata process described in the v2 section.

Keybinding reference chart

Use this chart when assessing new keybinding choices across platforms and common tools:

• https://en.wikipedia.org/wiki/Table_of_keyboard_shortcuts

Logging

Logging is essential for troubleshooting and debugging. Use ZoweLogger to write logs to both the Zowe Explorer log file and the VS Code output channel (Zowe Explorer) in one call.

Log levels

• ZoweLogger.trace: Fine-grained application behavior details.
• ZoweLogger.debug: Diagnostic information for troubleshooting.
• ZoweLogger.info: Routine application operation messages.
• ZoweLogger.warn: Potentially harmful occurrence messages.
• ZoweLogger.error: Serious problem occurrence messages.
• ZoweLogger.fatal: Catastrophic error event messages.

The extension log level setting is zowe.logger and defaults to INFO. To read this setting in code, use ZoweLogger.getLogSetting().

Related developer references

• Menu Commands
• File Save Flow
• Developing for Theia