@spscommerce/document-view-auto-localization

An automatic localization tool for the Document View FF functionality. Processes XSL stylesheets and replaces hardcoded text with localization calls.

Requirements

• Node.js >=24

Installation

pnpm add @spscommerce/document-view-auto-localization

Usage

import { autoLocalization } from '@spscommerce/document-view-auto-localization';

const xslText = `
  <xsl:stylesheet version="1.0">
    <p id="FieldLabel">Total Volume :</p>
  </xsl:stylesheet>
`;

const result = await autoLocalization(xslText);

console.log(result.xslText);
// <p id="FieldLabel">
//   <xsl:call-template name="translate">
//     <xsl:with-param name="id" select="'totalVolume'"/>
//     <xsl:with-param name="default" select="'Total Volume'"/>
//   </xsl:call-template> :
// </p>

console.log(result.foundTextTokens);
// [{ text: 'Total Volume :', key: 'totalVolume', textType: 'text', performedAction: 'canonical', quantityUsing: 1 }]

API

autoLocalization(xslText, options)

Processes an XSL stylesheet and replaces hardcoded text nodes with <xsl:call-template name="translate"> localization calls.

Signature:

async function autoLocalization(
  xslText: string,
  options?: AutoLocalizationOptions,
): Promise<ProcessingResults>

Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | xslText | string | Yes | The XSL stylesheet source text to process. Must be a valid non-empty XSL string. | | options | AutoLocalizationOptions | No | Configuration options for the localization process. |

AutoLocalizationOptions

| Property | Type | Default | Description | |----------|------|--------|-------------| | useConsoleLog | boolean | false | Enables verbose debug logging to the console. | | env | 'test' \| 'prod' | test | Specifies the runtime environment. Affects which canonical keys are loaded. | | ownCanonicalKeys | CanonicalKeys | — | Custom set of canonical keys to use instead of the built-in ones. |

Return value: ProcessingResults

| Property | Type | Description | |----------|------|-------------| | xslText | string | The processed XSL stylesheet with hardcoded text replaced by localization calls. | | foundTextTokens | FoundTextToken[] | List of all text tokens found and processed during transformation. |

FoundTextToken

| Property | Type | Description | |----------|------|-------------| | text | string | The original text found in the XSL. | | key | string | The translation key assigned to this text. | | textType | TextType | Whether the token is a plain text node ('text') or a legacy localization call ('legacy'). | | performedAction | PerformedAction | The action taken when resolving the key (see below). | | quantityUsing | number | How many times this text token was encountered in the XSL. |

PerformedAction values

| Value | Description | |-------|-------------| | 'canonical' | Text was matched exactly to an existing canonical key. | | 'canonical_normalized' | Text was matched to a canonical key after normalization (e.g. removing punctuation). | | 'new' | No canonical match found; a new key was generated from the text. | | 'unparsed_key' | A legacy $translate[@id='...'] call had an invalid or unparseable format. | | 'unresolved_key' | A legacy key was found but could not be resolved in the canonical keys. |

CanonicalKeys

See the full format specification in the https://support.phrase.com/hc/en-us/articles/20038313421468--JSON-Phrase-Strings.

In the package we use the following format:

type CanonicalKeys = Record<string, CanonicalKey>;

interface CanonicalKey {
  key: {
    plural?: boolean;
    max_characters_allowed?: number;
    description?: string;
    tags?: string[];
  };
  translations: {
    locale?: string;
    locale_code?: string;
    content: string;
  }[];
}

Errors

The function throws an error if xslText is an empty string.

How it works

1. Parses the XSL source text into a DOM tree.
2. Recursively walks all nodes looking for text content.
3. For each text node, attempts to resolve a translation key using three strategies in order:
   • Exact match against canonical keys.
   • Normalized match — strips punctuation/separators and tries again.
   • New key — generates a camelCase key from the text.
4. Replaces the text node with an <xsl:call-template name="translate"> element.
5. Handles legacy <xsl:value-of select="$translate[@id='...']"/> calls and transforms them into the new format.
6. Serializes the DOM back to an XSL string and returns it together with the token metadata.

Note: The new keys (PerformedAction = 'new') are not saving to any place, so you have to collect it and store to the Phrase.com project.