@readium/shared 2.0.0 → 2.1.1

package/src/publication/accessibility/Localization.md

@@ -0,0 +1,203 @@
+# Accessibility Metadata Localization
+
+This document explains how to use and customize the localization system for accessibility metadata in the `@readium/shared` package.
+
+## Overview
+
+The localization system allows consumers to provide their own translations for accessibility metadata strings while falling back to English if none is provided. The system uses a singleton pattern for easy access throughout the application and supports multiple registered locales.
+
+## Default Behavior
+
+By default, the system uses English (`en`) locale strings that are bundled with the package. These strings are included in the package and cover all accessibility metadata display needs.
+
+## Using the Localization System
+
+### Registering Custom Locales
+
+You can register new locales or override existing ones using the `registerLocale` method:
+
+```typescript
+// Register a new locale
+Localization.registerLocale('es', {
+  conformance: {
+    aaa: {
+      compact: "WCAG 2.1 Nivel AAA",
+      descriptive: "Esta publicación cumple con WCAG 2.1 Nivel AAA."
+    }
+  }
+});
+
+// Or override an existing locale
+Localization.registerLocale('en', {
+  conformance: {
+    aaa: {
+      compact: "WCAG 2.1 Level AAA (Custom)",
+      descriptive: "This publication conforms to WCAG 2.1 Level AAA (Custom)."
+    }
+  }
+});
+```
+
+### Setting the Current Locale
+
+```typescript
+// Set the current locale by language code
+Localization.setLocale('es');
+
+// Check if the locale was set successfully
+if (Localization.setLocale('es')) {
+  console.log('Locale set successfully');
+} else {
+  console.log('Locale not available');
+}
+```
+
+### Getting Localized Strings
+
+```typescript
+// Get a localized string
+const text = Localization.getString('conformance.aaa');
+// Returns: { compact: "WCAG 2.1 Nivel AAA", descriptive: "..." }
+```
+
+### Getting Available Locales
+
+```typescript
+// Get list of available locale codes
+const availableLocales = Localization.getAvailableLocales();
+// Returns: ['en', 'fr', 'es', ...]
+
+// Get current locale code
+const currentLocale = Localization.getCurrentLocale();
+// Returns: 'es'
+```
+
+## Locale Object Structure
+
+The locale object is a nested structure where:
+- Keys are nested objects representing the path to the value
+- Values can be either:
+  - A string, which will be used for both `compact` and `descriptive` values
+  - An object with `compact` and `descriptive` string properties
+
+Example of valid locale values:
+
+```typescript
+const locale = {
+  conformance: {
+    aaa: "This publication conforms to WCAG 2.1 Level AAA",
+    hazards: {
+      none: {
+        compact: "No hazards",
+        descriptive: "This content is known to be free of hazards."
+      }
+    }
+  }
+};
+```
+
+## Fallback Behavior
+
+If a key is not found in the custom locale, the system will fall back to the English locale. If the key is not found in either locale, a warning will be logged to the console and an empty string will be returned.
+
+## Available Locale Keys
+
+The following keys are used throughout the accessibility metadata system:
+
+### Conformance
+- `conformance.no`
+- `conformance.a`
+- `conformance.aa`
+- `conformance.aaa`
+- `conformance.unknown-standard`
+
+### Hazards
+- `hazards.none`
+- `hazards.unknown`
+- `hazards.no-metadata`
+- `hazards.flashing`
+- `hazards.flashing-unknown`
+- `hazards.flashing-none`
+- `hazards.motion`
+- `hazards.motion-unknown`
+- `hazards.motion-none`
+- `hazards.sound`
+- `hazards.sound-unknown`
+- `hazards.sound-none`
+
+### Navigation
+- `navigation.toc`
+- `navigation.index`
+- `navigation.structural`
+- `navigation.page-navigation`
+- `navigation.no-metadata`
+
+### Rich Content
+- `rich-content.extended-descriptions`
+- `rich-content.accessible-math-described`
+- `rich-content.accessible-math-as-mathml`
+- `rich-content.accessible-math-as-latex`
+- `rich-content.accessible-chemistry-as-mathml`
+- `rich-content.accessible-chemistry-as-latex`
+- `rich-content.closed-captions`
+- `rich-content.open-captions`
+- `rich-content.transcript`
+- `rich-content.unknown`
+
+### Additional Accessibility Information
+- `additional-accessibility-information.page-breaks`
+- `additional-accessibility-information.aria`
+- `additional-accessibility-information.audio-descriptions`
+- `additional-accessibility-information.braille`
+- `additional-accessibility-information.ruby-annotations`
+- `additional-accessibility-information.full-ruby-annotations`
+- `additional-accessibility-information.high-contrast-between-foreground-and-background-audio`
+- `additional-accessibility-information.high-contrast-between-text-and-background`
+- `additional-accessibility-information.large-print`
+- `additional-accessibility-information.sign-language`
+- `additional-accessibility-information.tactile-graphics`
+- `additional-accessibility-information.tactile-objects`
+- `additional-accessibility-information.text-to-speech-hinting`
+
+### Legal Considerations
+- `legal-considerations.exempt`
+- `legal-considerations.no-metadata`
+
+### Accessibility Summary
+- `accessibility-summary.no-metadata`
+
+## Best Practices
+
+1. **Provide both compact and descriptive versions** when possible by using an object with both properties. This allows for more precise control over the display text.
+2. **Test your custom locales** to ensure all necessary keys are provided.
+3. **Handle missing translations gracefully** - the system will log warnings for missing keys.
+
+## TypeScript Support
+
+When using TypeScript, the locale object should match the following structure:
+
+```typescript
+type LocalizedValue = string | {
+  compact: string;
+  descriptive: string;
+};
+
+type LocaleObject = {
+  [key: string]: LocalizedValue;
+};
+
+// Example usage:
+const customLocale = {
+  conformance: {
+    aaa: "This publication conforms to WCAG 2.1 Level AAA",
+    ...
+  },
+  hazards: {
+    none: {
+      compact: "No hazards",
+      descriptive: "This content is known to be free of hazards."
+    },
+    ...
+  }
+};
+```

package/src/publication/accessibility/Localization.ts

@@ -0,0 +1,115 @@
+// Localization.ts
+import enUS from './locales/en.json';
+import frFR from './locales/fr.json';
+
+export interface L10nString {
+  compact: string;
+  descriptive: string;
+}
+
+type LocaleData = Record<string, any>;
+
+class LocalizationImpl {
+  private static instance: LocalizationImpl;
+  private currentLocaleCode: string = 'en';
+  private locale: LocaleData = enUS;
+  private availableLocales: Record<string, LocaleData> = {
+    'en': enUS,
+    'fr': frFR
+  };
+
+  private constructor() {}
+
+  public static getInstance(): LocalizationImpl {
+    if (!LocalizationImpl.instance) {
+      LocalizationImpl.instance = new LocalizationImpl();
+    }
+    return LocalizationImpl.instance;
+  }
+
+  /**
+   * Registers a new locale or updates an existing one
+   * @param localeCode BCP 47 language code (e.g., 'en', 'fr-FR')
+   * @param localeData The locale data to register
+   */
+  public registerLocale(localeCode: string, localeData: LocaleData): void {
+    if (!localeCode || typeof localeCode !== 'string') {
+      throw new Error('Locale code must be a non-empty string');
+    }
+    this.availableLocales[localeCode] = localeData;
+  }
+
+  /**
+   * Sets the current locale by language code
+   * @param localeCode BCP 47 language code (e.g., 'en', 'fr-FR')
+   * @returns boolean indicating if the locale was set successfully
+   */
+  public setLocale(localeCode: string): boolean {
+    if (!(localeCode in this.availableLocales)) {
+      console.warn(`Locale '${localeCode}' is not available`);
+      return false;
+    }
+    this.locale = this.availableLocales[localeCode];
+    this.currentLocaleCode = localeCode;
+    return true;
+  }
+
+  /**
+   * Gets the current locale code (BCP 47)
+   */
+  public getCurrentLocale(): string {
+    return this.currentLocaleCode;
+  }
+
+  /**
+   * Gets a list of available locale codes
+   */
+  public getAvailableLocales(): string[] {
+    return Object.keys(this.availableLocales);
+  }
+
+  private getNestedValue(obj: any, path: string): string | L10nString | undefined {
+    const parts = path.split('.');
+    let current = obj;
+    
+    for (const part of parts) {
+      if (current === null || current === undefined) {
+        return undefined;
+      }
+      current = current[part];
+    }
+    
+    return current;
+  }
+
+  /**
+   * Gets a localized string by key
+   * @param key The key for the string to retrieve
+   * @returns The localized string as a [L10nString], or an empty string if not found
+   */
+  public getString(key: string): L10nString {
+    // First try the current locale
+    let value = this.getNestedValue(this.locale, key);
+    
+    // If not found and current locale is not English, try falling back to English
+    if (value === undefined && this.currentLocaleCode !== 'en') {
+      value = this.getNestedValue(this.availableLocales['en'], key);
+    }
+    
+    // If we have a value, return it with proper formatting
+    if (value !== undefined) {
+      return typeof value === 'string' 
+        ? { compact: value, descriptive: value } 
+        : value;
+    }
+    
+    // If we get here, the key wasn't found in either locale
+    console.warn(`Missing localization for key: ${key}`);
+    return { compact: '', descriptive: '' };
+  }
+}
+
+/**
+ * The singleton instance of the [Localization] class.
+ */
+export const Localization = LocalizationImpl.getInstance();

package/src/publication/accessibility/index.ts

@@ -0,0 +1,3 @@
+export * from './Accessibility';
+export * from './AccessibilityMetadataDisplayGuide';
+export * from './Localization';

package/src/publication/accessibility/locales/en.json

@@ -0,0 +1,231 @@
+{
+  "ways-of-reading": {
+    "title": "Ways of reading",
+    "nonvisual-reading": {
+      "alt-text": {
+        "compact": "Has alternative text",
+        "descriptive": "Has alternative text descriptions for images"
+      },
+      "no-metadata": "No information about nonvisual reading is available",
+      "none": {
+        "compact": "Not readable in read aloud or dynamic braille",
+        "descriptive": "The content is not readable as read aloud speech or dynamic braille"
+      },
+      "not-fully": {
+        "compact": "Not fully readable in read aloud or dynamic braille",
+        "descriptive": "Not all of the content will be readable as read aloud speech or dynamic braille"
+      },
+      "readable": {
+        "compact": "Readable in read aloud or dynamic braille",
+        "descriptive": "All content can be read as read aloud speech or dynamic braille"
+      }
+    },
+    "prerecorded-audio": {
+      "complementary": {
+        "compact": "Prerecorded audio clips",
+        "descriptive": "Prerecorded audio clips are embedded in the content"
+      },
+      "no-metadata": "No information about prerecorded audio is available",
+      "only": {
+        "compact": "Prerecorded audio only",
+        "descriptive": "Audiobook with no text alternative"
+      },
+      "synchronized": {
+        "compact": "Prerecorded audio synchronized with text",
+        "descriptive": "All the content is available as prerecorded audio synchronized with text"
+      }
+    },
+    "visual-adjustments": {
+      "modifiable": {
+        "compact": "Appearance can be modified",
+        "descriptive": "Appearance of the text and page layout can be modified according to the capabilities of the reading system (font family and font size, spaces between paragraphs, sentences, words, and letters, as well as color of background and text)"
+      },
+      "unknown": "No information about appearance modifiability is available",
+      "unmodifiable": {
+        "compact": "Appearance cannot be modified",
+        "descriptive": "Text and page layout cannot be modified as the reading experience is close to a print version, but reading systems can still provide zooming options"
+      }
+    }
+  },
+  "conformance": {
+    "title": "Conformance",
+    "details-title": "Detailed conformance information",
+    "a": {
+      "compact": "This publication meets minimum accessibility standards",
+      "descriptive": "The publication contains a conformance statement that it meets the EPUB Accessibility and WCAG 2 Level A standard"
+    },
+    "aa": {
+      "compact": "This publication meets accepted accessibility standards",
+      "descriptive": "The publication contains a conformance statement that it meets the EPUB Accessibility and WCAG 2 Level AA standard"
+    },
+    "aaa": {
+      "compact": "This publication exceeds accepted accessibility standards",
+      "descriptive": "The publication contains a conformance statement that it meets the EPUB Accessibility and WCAG 2 Level AAA standard"
+    },
+    "no": "No information is available",
+    "unknown-standard": "Conformance to accepted standards for accessibility of this publication cannot be determined",
+    "certifier": "The publication was certified by ",
+    "certifier-credentials": "The certifier's credential is ",
+    "details": {
+      "certification-info": "The publication was certified on ",
+      "certifier-report": "For more information refer to the certifier's report",
+      "claim": "This publication claims to meet",
+      "epub-accessibility-1-0": "EPUB Accessibility 1.0",
+      "epub-accessibility-1-1": "EPUB Accessibility 1.1",
+      "level-a": "Level A",
+      "level-aa": "Level AA",
+      "level-aaa": "Level AAA",
+      "wcag-2-0": {
+        "compact": "WCAG 2.0",
+        "descriptive": "Web Content Accessibility Guidelines (WCAG) 2.0"
+      },
+      "wcag-2-1": {
+        "compact": "WCAG 2.1",
+        "descriptive": "Web Content Accessibility Guidelines (WCAG) 2.1"
+      },
+      "wcag-2-2": {
+        "compact": "WCAG 2.2",
+        "descriptive": "Web Content Accessibility Guidelines (WCAG) 2.2"
+      }
+    }
+  },
+  "navigation": {
+    "title": "Navigation",
+    "index": {
+      "compact": "Index",
+      "descriptive": "Index with links to referenced entries"
+    },
+    "no-metadata": "No information is available",
+    "page-navigation": {
+      "compact": "Go to page",
+      "descriptive": "Page list to go to pages from the print source version"
+    },
+    "structural": {
+      "compact": "Headings",
+      "descriptive": "Elements such as headings, tables, etc for structured navigation"
+    },
+    "toc": {
+      "compact": "Table of contents",
+      "descriptive": "Table of contents to all chapters of the text via links"
+    }
+  },
+  "rich-content": {
+    "title": "Rich content",
+    "accessible-chemistry-as-latex": {
+      "compact": "Chemical formulas in LaTeX",
+      "descriptive": "Chemical formulas in accessible format (LaTeX)"
+    },
+    "accessible-chemistry-as-mathml": {
+      "compact": "Chemical formulas in MathML",
+      "descriptive": "Chemical formulas in accessible format (MathML)"
+    },
+    "accessible-math-as-latex": {
+      "compact": "Math as LaTeX",
+      "descriptive": "Math formulas in accessible format (LaTeX)"
+    },
+    "math-as-mathml": {
+      "compact": "Math as MathML",
+      "descriptive": "Math formulas in accessible format (MathML)"
+    },
+    "accessible-math-described": "Text descriptions of math are provided",
+    "closed-captions": {
+      "compact": "Videos have closed captions",
+      "descriptive": "Videos included in publications have closed captions"
+    },
+    "extended-descriptions": "Information-rich images are described by extended descriptions",
+    "open-captions": {
+      "compact": "Videos have open captions",
+      "descriptive": "Videos included in publications have open captions"
+    },
+    "transcript": "Transcript(s) provided",
+    "unknown": "No information is available"
+  },
+  "hazards": {
+    "title": "Hazards",
+    "flashing": {
+      "compact": "Flashing content",
+      "descriptive": "The publication contains flashing content that can cause photosensitive seizures"
+    },
+    "flashing-none": {
+      "compact": "No flashing hazards",
+      "descriptive": "The publication does not contain flashing content that can cause photosensitive seizures"
+    },
+    "flashing-unknown": {
+      "compact": "Flashing hazards not known",
+      "descriptive": "The presence of flashing content that can cause photosensitive seizures could not be determined"
+    },
+    "motion": {
+      "compact": "Motion simulation",
+      "descriptive": "The publication contains motion simulations that can cause motion sickness"
+    },
+    "motion-none": {
+      "compact": "No motion simulation hazards",
+      "descriptive": "The publication does not contain motion simulations that can cause motion sickness"
+    },
+    "motion-unknown": {
+      "compact": "Motion simulation hazards not known",
+      "descriptive": "The presence of motion simulations that can cause motion sickness could not be determined"
+    },
+    "no-metadata": "No information is available",
+    "none": {
+      "compact": "No hazards",
+      "descriptive": "The publication contains no hazards"
+    },
+    "sound": {
+      "compact": "Sounds",
+      "descriptive": "The publication contains sounds that can cause sensitivity issues"
+    },
+    "sound-none": {
+      "compact": "No sound hazards",
+      "descriptive": "The publication does not contain sounds that can cause sensitivity issues"
+    },
+    "sound-unknown": {
+      "compact": "Sound hazards not known",
+      "descriptive": "The presence of sounds that can cause sensitivity issues could not be determined"
+    },
+    "unknown": "The presence of hazards is unknown"
+  },
+  "accessibility-summary": {
+    "title": "Accessibility summary",
+    "no-metadata": "No information is available",
+    "publisher-contact": "For more information about the accessibility of this product, please contact the publisher: "
+  },
+  "legal-considerations": {
+    "title": "Legal considerations",
+    "exempt": {
+      "compact": "Claims an accessibility exemption in some jurisdictions",
+      "descriptive": "This publication claims an accessibility exemption in some jurisdictions"
+    },
+    "no-metadata": "No information is available"
+  },
+  "additional-accessibility-information": {
+    "title": "Additional accessibility information",
+    "aria": {
+      "compact": "ARIA roles included",
+      "descriptive": "Content is enhanced with ARIA roles to optimize organization and facilitate navigation"
+    },
+    "audio-descriptions": "Audio descriptions",
+    "braille": "Braille",
+    "color-not-sole-means-of-conveying-information": "Color is not the sole means of conveying information",
+    "dyslexia-readability": "Dyslexia readability",
+    "full-ruby-annotations": "Full ruby annotations",
+    "high-contrast-between-foreground-and-background-audio": "High contrast between foreground and background audio",
+    "high-contrast-between-text-and-background": "High contrast between foreground text and background",
+    "large-print": "Large print",
+    "page-breaks": {
+      "compact": "Page breaks included",
+      "descriptive": "Page breaks included from the original print source"
+    },
+    "ruby-annotations": "Some Ruby annotations",
+    "sign-language": "Sign language",
+    "tactile-graphics": {
+      "compact": "Tactile graphics included",
+      "descriptive": "Tactile graphics have been integrated to facilitate access to visual elements for blind people"
+    },
+    "tactile-objects": "Tactile 3D objects",
+    "text-to-speech-hinting": "Text-to-speech hinting provided",
+    "ultra-high-contrast-between-text-and-background": "Ultra high contrast between text and background",
+    "visible-page-numbering": "Visible page numbering",
+    "without-background-sounds": "Without background sounds"
+  }
+}