VSCode extensions must comply with Web Content Accessibility Guidelines (WCAG) 2.1 Level AA. The extension host environment provides native support for screen readers, keyboard navigation, and high contrast themes. Accessibility implementation is primarily achieved through semantic HTML elements and ARIA attributes in webviews, as well as correct API usage for native UI components.
Commands must provide screen reader-friendly descriptions and keyboard shortcuts:
// src/accessibleCommands.ts
export function registerAccessibleCommands(context: vscode.ExtensionContext): void {
const commands = [
{
command: 'extension.formatCode',
title: 'Format TypeScript Code',
category: 'TypeScript Tools',
description: 'Formats the currently selected TypeScript code block',
keybinding: 'ctrl+shift+f',
handler: formatCodeHandler
},
{
command: 'extension.showDocumentation',
title: 'Show Documentation',
category: 'TypeScript Tools',
description: 'Opens documentation for the symbol under cursor',
keybinding: 'f1',
handler: showDocumentationHandler
}
];
commands.forEach(cmd => {
const disposable = vscode.commands.registerCommand(
cmd.command,
cmd.handler
);
context.subscriptions.push(disposable);
});
}
async function formatCodeHandler(): Promise<void> {
const editor = vscode.window.activeTextEditor;
if (!editor) {
// Accessibility: Informative error messages
vscode.window.showErrorMessage(
'No active editor found. Please open a TypeScript file and try again.'
);
return;
}
const document = editor.document;
if (document.languageId !== 'typescript') {
vscode.window.showWarningMessage(
'Current file is not a TypeScript file. This command works only with TypeScript files.'
);
return;
}
try {
await vscode.commands.executeCommand('editor.action.formatDocument');
// Accessibility: Success feedback
vscode.window.showInformationMessage(
'TypeScript code formatted successfully.'
);
} catch (error) {
vscode.window.showErrorMessage(
`Formatting failed: ${error.message}`
);
}
}Webviews require explicit accessibility implementation through semantic HTML and ARIA attributes:
// src/accessibleWebview.ts
export class AccessibleWebviewProvider implements vscode.WebviewViewProvider {
public resolveWebviewView(webviewView: vscode.WebviewView): void {
webviewView.webview.options = {
enableScripts: true,
localResourceRoots: []
};
webviewView.webview.html = this.getAccessibleHtml();
// Message handling with accessibility feedback
webviewView.webview.onDidReceiveMessage(message => {
this.handleAccessibleMessage(message, webviewView);
});
}
private getAccessibleHtml(): string {
return `
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>TypeScript Tools</title>
<style>
/* High Contrast Theme Support */
body {
background-color: var(--vscode-editor-background);
color: var(--vscode-editor-foreground);
font-family: var(--vscode-font-family);
font-size: var(--vscode-font-size);
}
/* Focus indicators */
button:focus, input:focus, select:focus {
outline: 2px solid var(--vscode-focusBorder);
outline-offset: 2px;
}
/* Accessible color contrast */
.error {
color: var(--vscode-errorForeground);
background-color: var(--vscode-inputValidation-errorBackground);
}
.success {
color: var(--vscode-terminal-ansiGreen);
}
/* Screen reader only content */
.sr-only {
position: absolute;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
overflow: hidden;
clip: rect(0, 0, 0, 0);
white-space: nowrap;
border: 0;
}
</style>
</head>
<body>
<main role="main" aria-label="TypeScript Tools Panel">
<header>
<h1 id="panel-title">TypeScript Code Analysis</h1>
<p class="sr-only">Use Tab to navigate between controls</p>
</header>
<section aria-labelledby="analysis-section">
<h2 id="analysis-section">Code Analysis Options</h2>
<form role="form" aria-label="Analysis Configuration">
<fieldset>
<legend>Analysis Type</legend>
<div role="radiogroup" aria-labelledby="analysis-type-label">
<label id="analysis-type-label" class="sr-only">
Select analysis type
</label>
<label>
<input type="radio" name="analysisType" value="syntax"
aria-describedby="syntax-desc" checked>
Syntax Analysis
</label>
<p id="syntax-desc" class="description">
Analyzes TypeScript syntax for errors
</p>
<label>
<input type="radio" name="analysisType" value="semantic"
aria-describedby="semantic-desc">
Semantic Analysis
</label>
<p id="semantic-desc" class="description">
Performs deep semantic analysis
</p>
</div>
</fieldset>
<div class="form-group">
<label for="file-filter">File Filter Pattern</label>
<input type="text" id="file-filter" name="fileFilter"
aria-describedby="filter-help"
placeholder="**/*.ts">
<p id="filter-help" class="help-text">
Glob pattern to filter files (e.g., **/*.ts for all TypeScript files)
</p>
</div>
<div class="form-actions">
<button type="submit" id="analyze-btn"
aria-describedby="analyze-desc">
Start Analysis
</button>
<p id="analyze-desc" class="sr-only">
Starts code analysis with selected options
</p>
<button type="button" id="clear-btn"
aria-label="Clear results">
Clear Results
</button>
</div>
</form>
</section>
<section aria-labelledby="results-section" aria-live="polite">
<h2 id="results-section">Analysis Results</h2>
<div id="results-container" role="region"
aria-label="Analysis results"
aria-describedby="results-status">
<p id="results-status">No analysis performed yet</p>
</div>
</section>
</main>
<script>
const vscode = acquireVsCodeApi();
// Keyboard navigation support
document.addEventListener('keydown', (event) => {
// Escape key closes dialogs
if (event.key === 'Escape') {
closeActiveDialog();
}
// Enter key activates focused button
if (event.key === 'Enter' && event.target.tagName === 'BUTTON') {
event.target.click();
}
});
// Form submission with accessibility feedback
document.getElementById('analyze-btn').addEventListener('click', (event) => {
event.preventDefault();
const formData = new FormData(document.forms[0]);
const analysisType = formData.get('analysisType');
const fileFilter = formData.get('fileFilter');
// Update screen reader status
updateAriaLiveRegion('Starting analysis...');
vscode.postMessage({
command: 'startAnalysis',
analysisType,
fileFilter
});
});
// Clear results with accessibility feedback
document.getElementById('clear-btn').addEventListener('click', () => {
document.getElementById('results-container').innerHTML =
'<p id="results-status">Results cleared</p>';
updateAriaLiveRegion('Results cleared');
});
// Accessibility helper functions
function updateAriaLiveRegion(message) {
const statusElement = document.getElementById('results-status');
statusElement.textContent = message;
}
function closeActiveDialog() {
// Implementation for dialog closing
}
// Message handling from extension
window.addEventListener('message', event => {
const message = event.data;
switch (message.command) {
case 'analysisComplete':
displayResults(message.results);
updateAriaLiveRegion('Analysis completed');
break;
case 'analysisError':
displayError(message.error);
updateAriaLiveRegion('Analysis failed');
break;
}
});
function displayResults(results) {
const container = document.getElementById('results-container');
container.innerHTML = \`
<table role="table" aria-label="Analysis results">
<thead>
<tr>
<th scope="col">File</th>
<th scope="col">Line</th>
<th scope="col">Issue</th>
<th scope="col">Severity</th>
</tr>
</thead>
<tbody>
\${results.map(result => \`
<tr>
<td>\${result.file}</td>
<td>\${result.line}</td>
<td>\${result.message}</td>
<td>
<span class="\${result.severity}"
aria-label="Severity: \${result.severity}">
\${result.severity}
</span>
</td>
</tr>
\`).join('')}
</tbody>
</table>
\`;
}
</script>
</body>
</html>
`;
}
}VSCode uses a JSON-based i18n system with language-specific message bundles:
// src/i18n/i18nManager.ts
export class I18nManager {
private static instance: I18nManager;
private messages: Map<string, string> = new Map();
private locale: string;
private fallbackLocale = 'en';
private constructor() {
this.locale = this.detectLocale();
this.loadMessages();
}
public static getInstance(): I18nManager {
if (!I18nManager.instance) {
I18nManager.instance = new I18nManager();
}
return I18nManager.instance;
}
private detectLocale(): string {
// VSCode locale detection
const config = vscode.workspace.getConfiguration();
const vsCodeLocale = config.get<string>('locale');
if (vsCodeLocale) {
return vsCodeLocale;
}
// System locale fallback
const systemLocale = process.env.LANG || process.env.LANGUAGE || 'en';
return systemLocale.split('.')[0].replace('_', '-');
}
private async loadMessages(): Promise<void> {
try {
const messagesPath = path.join(__dirname, '..', 'i18n', `${this.locale}.json`);
const messagesContent = await fs.readFile(messagesPath, 'utf8');
const messages = JSON.parse(messagesContent);
Object.entries(messages).forEach(([key, value]) => {
this.messages.set(key, value as string);
});
} catch (error) {
// Fallback to English
console.warn(`Failed to load locale ${this.locale}, falling back to ${this.fallbackLocale}`);
if (this.locale !== this.fallbackLocale) {
this.locale = this.fallbackLocale;
await this.loadMessages();
}
}
}
public getMessage(key: string, ...args: any[]): string {
const template = this.messages.get(key) || key;
return this.interpolate(template, args);
}
private interpolate(template: string, args: any[]): string {
return template.replace(/\{(\d+)\}/g, (match, index) => {
const argIndex = parseInt(index, 10);
return args[argIndex] !== undefined ? String(args[argIndex]) : match;
});
}
public getPlural(key: string, count: number, ...args: any[]): string {
const pluralKey = count === 1 ? `${key}.singular` : `${key}.plural`;
return this.getMessage(pluralKey, count, ...args);
}
public formatDate(date: Date, format: 'short' | 'medium' | 'long' = 'medium'): string {
const options: Intl.DateTimeFormatOptions = {
short: { dateStyle: 'short' },
medium: { dateStyle: 'medium' },
long: { dateStyle: 'long' }
}[format];
return new Intl.DateTimeFormat(this.locale, options).format(date);
}
public formatNumber(value: number, options?: Intl.NumberFormatOptions): string {
return new Intl.NumberFormat(this.locale, options).format(value);
}
public isRTL(): boolean {
const rtlLocales = ['ar', 'he', 'fa', 'ur'];
return rtlLocales.some(rtl => this.locale.startsWith(rtl));
}
}Language-specific JSON files for localization:
// i18n/en.json
{
"extension.displayName": "TypeScript Development Tools",
"extension.description": "Professional TypeScript development tools for VSCode",
"commands.formatCode.title": "Format TypeScript Code",
"commands.formatCode.description": "Formats the currently selected TypeScript code block",
"commands.showDocumentation.title": "Show Documentation",
"messages.noActiveEditor": "No active editor found. Please open a TypeScript file and try again.",
"messages.notTypeScriptFile": "Current file is not a TypeScript file. This command works only with TypeScript files.",
"messages.formatSuccess": "TypeScript code formatted successfully.",
"messages.formatError": "Formatting failed: {0}",
"analysis.syntaxCheck": "Syntax Analysis",
"analysis.semanticCheck": "Semantic Analysis",
"analysis.startAnalysis": "Start Analysis",
"analysis.clearResults": "Clear Results",
"analysis.resultsCleared": "Results cleared",
"analysis.analysisComplete": "Analysis completed",
"analysis.analysisFailed": "Analysis failed",
"results.file": "File",
"results.line": "Line",
"results.issue": "Issue",
"results.severity": "Severity",
"errors.singular": "Found {0} error",
"errors.plural": "Found {0} errors",
"warnings.singular": "Found {0} warning",
"warnings.plural": "Found {0} warnings",
"accessibility.screenReaderInstructions": "Use Tab to navigate between controls",
"accessibility.analysisResults": "Analysis results",
"accessibility.severityLevel": "Severity: {0}"
}// i18n/de.json
{
"extension.displayName": "TypeScript Entwicklungstools",
"extension.description": "Professionelle TypeScript-Entwicklungstools für VSCode",
"commands.formatCode.title": "TypeScript-Code formatieren",
"commands.formatCode.description": "Formatiert den aktuell ausgewählten TypeScript-Codeblock",
"commands.showDocumentation.title": "Dokumentation anzeigen",
"messages.noActiveEditor": "Kein aktiver Editor gefunden. Bitte öffnen Sie eine TypeScript-Datei und versuchen Sie es erneut.",
"messages.notTypeScriptFile": "Die aktuelle Datei ist keine TypeScript-Datei. Dieser Befehl funktioniert nur mit TypeScript-Dateien.",
"messages.formatSuccess": "TypeScript-Code erfolgreich formatiert.",
"messages.formatError": "Formatierung fehlgeschlagen: {0}",
"analysis.syntaxCheck": "Syntaxanalyse",
"analysis.semanticCheck": "Semantische Analyse",
"analysis.startAnalysis": "Analyse starten",
"analysis.clearResults": "Ergebnisse löschen",
"analysis.resultsCleared": "Ergebnisse gelöscht",
"analysis.analysisComplete": "Analyse abgeschlossen",
"analysis.analysisFailed": "Analyse fehlgeschlagen",
"results.file": "Datei",
"results.line": "Zeile",
"results.issue": "Problem",
"results.severity": "Schweregrad",
"errors.singular": "{0} Fehler gefunden",
"errors.plural": "{0} Fehler gefunden",
"warnings.singular": "{0} Warnung gefunden",
"warnings.plural": "{0} Warnungen gefunden",
"accessibility.screenReaderInstructions": "Verwenden Sie Tab zum Navigieren zwischen Steuerelementen",
"accessibility.analysisResults": "Analyseergebnisse",
"accessibility.severityLevel": "Schweregrad: {0}"
}Integration of i18n in extension configuration:
// src/localizedExtension.ts
export function activate(context: vscode.ExtensionContext): void {
const i18n = I18nManager.getInstance();
// Register localized commands
const commands = [
{
command: 'extension.formatCode',
title: i18n.getMessage('commands.formatCode.title'),
handler: () => formatCodeWithI18n(i18n)
},
{
command: 'extension.showDocumentation',
title: i18n.getMessage('commands.showDocumentation.title'),
handler: () => showDocumentationWithI18n(i18n)
}
];
commands.forEach(cmd => {
const disposable = vscode.commands.registerCommand(cmd.command, cmd.handler);
context.subscriptions.push(disposable);
});
// Localized status bar items
const statusBarItem = vscode.window.createStatusBarItem(
vscode.StatusBarAlignment.Left,
100
);
statusBarItem.text = i18n.getMessage('statusBar.ready');
statusBarItem.show();
context.subscriptions.push(statusBarItem);
}
async function formatCodeWithI18n(i18n: I18nManager): Promise<void> {
const editor = vscode.window.activeTextEditor;
if (!editor) {
vscode.window.showErrorMessage(
i18n.getMessage('messages.noActiveEditor')
);
return;
}
const document = editor.document;
if (document.languageId !== 'typescript') {
vscode.window.showWarningMessage(
i18n.getMessage('messages.notTypeScriptFile')
);
return;
}
try {
await vscode.commands.executeCommand('editor.action.formatDocument');
vscode.window.showInformationMessage(
i18n.getMessage('messages.formatSuccess')
);
} catch (error) {
vscode.window.showErrorMessage(
i18n.getMessage('messages.formatError', error.message)
);
}
}Extension metadata for different languages:
{
"name": "typescript-tools",
"displayName": "%extension.displayName%",
"description": "%extension.description%",
"contributes": {
"commands": [
{
"command": "extension.formatCode",
"title": "%commands.formatCode.title%",
"category": "TypeScript"
}
],
"configuration": {
"title": "%configuration.title%",
"properties": {
"typescript-tools.enableLinting": {
"type": "boolean",
"default": true,
"description": "%configuration.enableLinting.description%"
},
"typescript-tools.maxErrors": {
"type": "number",
"default": 100,
"description": "%configuration.maxErrors.description%"
}
}
}
}
}Corresponding package.nls.json for default language:
{
"extension.displayName": "TypeScript Development Tools",
"extension.description": "Professional TypeScript development tools",
"commands.formatCode.title": "Format TypeScript Code",
"configuration.title": "TypeScript Tools Configuration",
"configuration.enableLinting.description": "Enable TypeScript linting",
"configuration.maxErrors.description": "Maximum number of errors to display"
}German localization in package.nls.de.json:
{
"extension.displayName": "TypeScript Entwicklungstools",
"extension.description": "Professionelle TypeScript-Entwicklungstools",
"commands.formatCode.title": "TypeScript-Code formatieren",
"configuration.title": "TypeScript Tools Konfiguration",
"configuration.enableLinting.description": "TypeScript-Linting aktivieren",
"configuration.maxErrors.description": "Maximale Anzahl der anzuzeigenden Fehler"
}Right-to-Left languages require special CSS treatment:
// src/rtlSupport.ts
export class RTLWebviewProvider implements vscode.WebviewViewProvider {
public resolveWebviewView(webviewView: vscode.WebviewView): void {
const i18n = I18nManager.getInstance();
const isRTL = i18n.isRTL();
webviewView.webview.html = this.getLocalizedHtml(i18n, isRTL);
}
private getLocalizedHtml(i18n: I18nManager, isRTL: boolean): string {
return `
<!DOCTYPE html>
<html lang="${i18n.locale}" dir="${isRTL ? 'rtl' : 'ltr'}">
<head>
<meta charset="UTF-8">
<title>${i18n.getMessage('extension.displayName')}</title>
<style>
body {
direction: ${isRTL ? 'rtl' : 'ltr'};
text-align: ${isRTL ? 'right' : 'left'};
}
.form-group {
margin-${isRTL ? 'right' : 'left'}: 0;
margin-${isRTL ? 'left' : 'right'}: 20px;
}
.icon {
float: ${isRTL ? 'right' : 'left'};
margin-${isRTL ? 'left' : 'right'}: 10px;
}
</style>
</head>
<body>
<h1>${i18n.getMessage('analysis.title')}</h1>
<button>${i18n.getMessage('analysis.startAnalysis')}</button>
</body>
</html>
`;
}
}Automated tests for accessibility compliance:
// src/test/accessibility.test.ts
import { expect } from 'chai';
import * as vscode from 'vscode';
describe('Accessibility Tests', () => {
let webview: vscode.Webview;
beforeEach(async () => {
// Setup test webview
});
it('should have proper ARIA labels', async () => {
const html = await getWebviewHtml();
// Check for required ARIA attributes
expect(html).to.include('aria-label=');
expect(html).to.include('role=');
expect(html).to.include('aria-describedby=');
});
it('should support keyboard navigation', async () => {
// Test keyboard event handling
const keyboardEvents = ['Tab', 'Enter', 'Escape', 'Space'];
keyboardEvents.forEach(key => {
// Simulate keyboard events and verify handling
});
});
it('should have sufficient color contrast', async () => {
const styles = await getComputedStyles();
// Verify WCAG AA compliance (4.5:1 ratio)
expect(styles.contrastRatio).to.be.at.least(4.5);
});
});| Aspect | Java/ResourceBundle | VSCode Extensions |
|---|---|---|
| Message Format | .properties | JSON |
| Pluralization | MessageFormat | Custom Logic |
| Locale Detection | Locale.getDefault() | VSCode API |
| Fallback Mechanism | ResourceBundle | Custom Implementation |
| Hot Reloading | No | Extension Restart |
| RTL Support | Manual | CSS + Logic |
Message Keys: Use hierarchical keys (e.g.,
commands.formatCode.title) for better organization.
Fallback Strategies: Always provide English fallback messages for missing translations.
Pluralization: Implement language-specific plural rules via ICU MessageFormat or custom logic.
Context-Sensitive Help: Adapt accessibility descriptions to UI context for better screen reader support.
Performance: Lazy load and cache message bundles to optimize startup performance.
Testing: Implement automated tests for different locales and accessibility compliance.
RTL Layout: Apply CSS properties for Right-to-Left languages conditionally.
Keyboard Navigation: Ensure complete keyboard accessibility for all interactive elements.
// Best Practice: Centralized i18n usage
const i18n = I18nManager.getInstance();
const message = i18n.getMessage('analysis.complete', resultCount);
const screenReaderText = i18n.getMessage('accessibility.analysisComplete', resultCount);