@expressive-code/core - npm Package Compare versions

Comparing version 0.5.0 to 0.6.0

dist/index.d.ts

@@ -173,2 +173,3 @@ import * as hast from 'hast';
     theme: ExpressiveCodeTheme;
+    locale: string;
     coreStyles: ResolvedCoreStyles;
@@ -378,12 +379,25 @@ /**
     /**
-     * An optional handler function that can initialize plugin data for the
-     * code block before processing starts.
+     * The code block's locale (e.g. `en-US` or `de-DE`). This is used by plugins to display
+     * localized strings depending on the language of the containing page.
      *
-     * Plugins can provide access to their data by exporting a const
-     * set to a `new AttachedPluginData(...)` instance (e.g. `myPluginData`).
+     * Integrations like `remark-expressive-code` support multi-language sites by allowing you
+     * to provide custom logic to determine a block's locale (e.g. based on its parent document).
      *
-     * You can then import the const and set `onInitBlock` to a function that
-     * calls `myPluginData.setFor(block, { ...data... })`.
+     * If no locale is defined here, `ExpressiveCodeEngine` will render the code block
+     * using the `defaultLocale` provided in its configuration.
      */
-    onInitBlock?: (block: ExpressiveCodeBlock) => void;
+    locale?: string;
+    /**
+     * Optional data about the parent document the code block is located in.
+     *
+     * Integrations like `remark-expressive-code` can provide this information based on the
+     * source document being processed. There may be cases where no document is available,
+     * e.g. when the code block was created dynamically.
+     */
+    parentDocument?: {
+        /**
+         * The full path to the source file containing the code block.
+         */
+        sourceFilePath?: string;
+    };
 }
@@ -404,2 +418,9 @@ declare class ExpressiveCodeBlock {
     set meta(value: string);
+    get locale(): string | undefined;
+    get parentDocument(): {
+        /**
+         * The full path to the source file containing the code block.
+         */
+        sourceFilePath?: string | undefined;
+    } | undefined;
     get state(): ExpressiveCodeProcessingState | undefined;
@@ -496,2 +517,6 @@ set state(value: ExpressiveCodeProcessingState | undefined);
     /**
+     * The locale that should be used for text content. Defaults to `en-US`.
+     */
+    defaultLocale?: string;
+    /**
      * An optional set of style overrides that can be used to customize the appearance of
@@ -538,2 +563,3 @@ * the rendered code blocks without having to write custom CSS. You can customize core
     readonly theme: ExpressiveCodeTheme;
+    readonly defaultLocale: string;
     readonly styleOverrides: Partial<typeof coreStyleSettings.defaultSettings>;
@@ -569,2 +595,54 @@ readonly coreStyles: ResolvedCoreStyles;
 
+type KnownTextsByKey<T extends {
+    [K: string]: string | (() => string);
+}> = {
+    [K in keyof T]: T[K];
+};
+declare class PluginTexts<Texts extends KnownTextsByKey<Texts>> {
+    readonly defaultTexts: Texts;
+    private readonly localizedTexts;
+    private readonly overridesByLocale;
+    constructor(defaultTexts: Texts);
+    /**
+     * Adds localized texts for a specific locale. You must provide a full set of localized texts
+     * for the given locale.
+     *
+     * It is recommended to use two-letter language codes (e.g. `de`, `fr`, `es`) without region
+     * codes to make your localized texts available to all users speaking the same language.
+     * Region codes should only be added if regional differences must be taken into account.
+     *
+     * Plugin authors can use this to provide localized versions of their texts.
+     * Users can also call this function to provide their own localizations.
+     *
+     * If you only want to customize a few texts of an existing localization,
+     * have a look at `overrideTexts` instead.
+     */
+    addLocale(locale: string, localizedTexts: Texts): void;
+    /**
+     * Allows you to override any defined texts. This is useful if you want to customize a few
+     * selected texts without having to provide a full set of localized texts.
+     *
+     * You can either override texts for a specific `locale`, or override the default texts
+     * by setting `locale` to `undefined`.
+     *
+     * It is recommended to use two-letter language codes (e.g. `de`, `fr`, `es`) without region
+     * codes to apply your overrides to all users speaking the same language.
+     * Region codes should only be added if regional differences must be taken into account.
+     */
+    overrideTexts(locale: string | undefined, localeTextOverrides: Partial<Texts>): void;
+    /**
+     * Returns the best matching texts for the requested locale,
+     * taking any available localized texts and overrides into account.
+     *
+     * Example for locale `de-DE`:
+     * - If localized texts for `de-DE` are available, these will be returned.
+     * - If `de-DE` is not available, but `de` is, these will be returned.
+     * - As the final fallback, the default texts will be returned.
+     */
+    get(locale: string): Texts;
+    private parseLocale;
+    private getLocalizedTexts;
+    private applyOverrides;
+}
+
 declare function addClass(node: Parent, className: string): void;
@@ -713,2 +791,2 @@
 
-export { AnnotationBaseOptions, AnnotationRenderOptions, AnnotationRenderPhase, AnnotationRenderPhaseOrder, AttachedPluginData, BaseStylesResolverFn, ColorDefinition, ColorValue, CoreStyleResolverFn, CoreStyleSettings, ExpressiveCodeAnnotation, ExpressiveCodeBlock, ExpressiveCodeBlockOptions, ExpressiveCodeEngine, ExpressiveCodeEngineConfig, ExpressiveCodeHook, ExpressiveCodeHookContext, ExpressiveCodeInlineRange, ExpressiveCodeLine, ExpressiveCodePlugin, ExpressiveCodePluginHookName, ExpressiveCodePluginHooks, ExpressiveCodePluginHooks_BeforeRendering, ExpressiveCodePluginHooks_Rendering, ExpressiveCodeTheme, InlineStyleAnnotation, JsModulesResolverFn, PluginDataTarget, PostprocessRenderedBlockContext, PostprocessRenderedBlockGroupContext, PostprocessRenderedLineContext, ReplaceDelimitedValuesMatch, ReplaceDelimitedValuesSyntax, ResolvedCoreStyles, ResolvedStyleSettings, StyleResolverFn, StyleSettings, UnresolvedCoreStyleSettings, UnresolvedStyleSettings, addClass, annotationSortFn, changeAlphaToReachColorContrast, changeLuminanceToReachColorContrast, codeLineClass, coreStyleSettings, darken, ensureColorContrastOnBackground, getColorContrast, getColorContrastOnBackground, getCoreBaseStyles, getGroupIndicesFromRegExpMatch, getStableObjectHash, lighten, mix, multiplyAlpha, onBackground, replaceDelimitedValues, runHooks, setAlpha, setLuminance, stableStringify, toHexColor, toRgbaString, validateExpressiveCodeAnnotation };
+export { AnnotationBaseOptions, AnnotationRenderOptions, AnnotationRenderPhase, AnnotationRenderPhaseOrder, AttachedPluginData, BaseStylesResolverFn, ColorDefinition, ColorValue, CoreStyleResolverFn, CoreStyleSettings, ExpressiveCodeAnnotation, ExpressiveCodeBlock, ExpressiveCodeBlockOptions, ExpressiveCodeEngine, ExpressiveCodeEngineConfig, ExpressiveCodeHook, ExpressiveCodeHookContext, ExpressiveCodeInlineRange, ExpressiveCodeLine, ExpressiveCodePlugin, ExpressiveCodePluginHookName, ExpressiveCodePluginHooks, ExpressiveCodePluginHooks_BeforeRendering, ExpressiveCodePluginHooks_Rendering, ExpressiveCodeTheme, InlineStyleAnnotation, JsModulesResolverFn, PluginDataTarget, PluginTexts, PostprocessRenderedBlockContext, PostprocessRenderedBlockGroupContext, PostprocessRenderedLineContext, ReplaceDelimitedValuesMatch, ReplaceDelimitedValuesSyntax, ResolvedCoreStyles, ResolvedStyleSettings, StyleResolverFn, StyleSettings, UnresolvedCoreStyleSettings, UnresolvedStyleSettings, addClass, annotationSortFn, changeAlphaToReachColorContrast, changeLuminanceToReachColorContrast, codeLineClass, coreStyleSettings, darken, ensureColorContrastOnBackground, getColorContrast, getColorContrastOnBackground, getCoreBaseStyles, getGroupIndicesFromRegExpMatch, getStableObjectHash, lighten, mix, multiplyAlpha, onBackground, replaceDelimitedValues, runHooks, setAlpha, setLuminance, stableStringify, toHexColor, toRgbaString, validateExpressiveCodeAnnotation };

package.json

 {
   "name": "@expressive-code/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A text marking & annotation engine for presenting source code on the web.",
@@ -5,0 +5,0 @@ "keywords": [],

README.md

@@ -311,10 +311,2 @@ # @expressive-code/core
 
-- ##### `onInitBlock?: (block: ExpressiveCodeBlock) => void`
-
-  An optional handler function that can initialize plugin data for the code block before processing starts.
-
-  Plugins can provide access to their data by exporting a const set to a `new AttachedPluginData(...)` instance (e.g. `myPluginData`).
-
-  You can then import the const and set `onInitBlock` to a function that calls `myPluginData.setFor(block, { ...data... })`.
-
 ---
@@ -321,0 +313,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

767664

increased by4.37%

Lines of code

8598

increased by5.23%

Worsened metrics

Number of lines in readme file

796

decreased by-1%

No dependency changes