Transloco Keys Manager (TKM)

V9 introduces stricter validation for command-line flags. The CLI now distinguishes between flags supported by a specific command and those that are not.

Behavior by Source

• Explicit CLI Flags: If you pass a flag that the specific command (e.g., extract) does not support, the CLI will throw a hard error and exit with a non-zero exit code.
• Configuration Files: Flags defined in your transloco.config.js or .ts file that are only relevant to other commands (e.g., setting emitErrorOnExtraKeys in a config used for both find and extract) will remain silent and will not cause errors. This ensures that shared configurations do not break automated workflows.

Common breaking scenarios

• Using a shared CI template that passes the same set of flags to both extract and find.
• Combining commands in an npm script like: tkm extract -e && tkm find -e (where -e is unsupported by extract).

In Transloco Keys Manager V9, the keysManager configuration object in TranslocoGlobalConfig has been restructured from a flat object into command-specific sections. This change ensures that configuration keys are only applied to the commands they are intended for (extract or find) and provides better TypeScript type safety.

Breaking Change

Every existing transloco.config.js that places command-specific keys at the top level of keysManager must be updated. Keys like output, replace, removeExtraKeys, addMissingKeys, or emitErrorOnExtraKeys must now be moved into their respective extract or find blocks.

New Configuration Structure

Example Migration

Before (V8):

keysManager: {
  input: 'src/assets/i18n',
  output: 'src/assets/i18n/en.json',
  addMissingKeys: true
}

After (V9):

keysManager: {
  input: 'src/assets/i18n',
  extract: {
    output: 'src/assets/i18n/en.json'
  },
  find: {
    addMissingKeys: true
  }
}

keysManager: {
  // read by both commands
  input?: string | string[];
  langs?: string[];
  fileFormat?: 'json' | 'pot';
  marker?: string;
  defaultValue?: string;
  sort?: boolean;
  unflat?: boolean;
  translationsPath?: string;

  extract?: { output?: string; replace?: boolean; removeExtraKeys?: boolean };
  find?: { addMissingKeys?: boolean; emitErrorOnExtraKeys?: boolean };
}

In version 5, the sourceRoot prefix is only applied to the default configuration. For all other configurations, you must provide the full path relative to the project root for rootTranslationsPath, keysManager.input, and keysManager.output.

Example Migration:

Before (v4 and below):

import {TranslocoGlobalConfig} from "@jsverse/transloco-utils";

const config: TranslocoGlobalConfig = {
   rootTranslationsPath: 'assets/i18n/',
   langs: ['it', 'en'],
   keysManager: {
       input: ['app'],
       output: 'assets/i18n/'
   },
}

export default config;

After (v5+):

import {TranslocoGlobalConfig} from "@jsverse/transloco-utils";

const config: TranslocoGlobalConfig = {
   // Prefix paths with the source root (e.g., 'src/')
   rootTranslationsPath: 'src/assets/i18n/',
   langs: ['it', 'en'],
   keysManager: {
       input: [
           'src/app', 
           'projects/ui-lib/src/lib' // Scanning non-buildable libs is now supported
       ],
       output: 'src/assets/i18n/'
   },
}

export default config;

The templateExtractor is the core logic used for HTML files. It follows these steps:

1. Content Loading: It reads the file content from the provided file path or uses config.content if provided.
2. Early Exit: If the content does not include the term transloco, it returns the current scopeToKeys immediately.
3. Template Parsing: It uses @angular/compiler's parseTemplate to create a parsed representation of the HTML.
4. Multi-stage Extraction: It executes a sequence of specialized extractors on the parsed template:
   • pipeExtractor: Finds keys used within pipes.
   • templateCommentsExtractor: Finds keys defined within HTML comments.
   • directiveExtractor: Finds keys used in standard directives.
   • structuralDirectiveExtractor: Finds keys used in structural directives (e.g., *ngIf).
5. Result: It returns the updated scopeToKeys containing all discovered keys.

The TypeScript extractor (TSExtractor) follows a multi-stage process to ensure all keys are captured:

1. Import Detection: It checks for imports from @jsverse/transloco or @ngneat/transloco and @jsverse/transloco-keys-manager. This determines which specialized extractors to run.
2. Specialized Extraction: If Transloco imports are found, it runs:
   • serviceExtractor: For keys used in Transloco services.
   • pureFunctionExtractor: For keys used in pure functions.
   • signalExtractor: For keys used in Signals.
   • markerExtractor: For keys identified via specific markers (if the keys-manager package is imported).
3. AST Parsing: If Transloco-related content is detected, it performs an AST parse using tsquery to accurately locate function calls and variable usages.
4. Comment & Template Scanning:
   • It scans file comments using addCommentSectionKeys to find keys manually defined in comments.
   • It uses inlineTemplateExtractor to find keys within inline templates found in the AST.