Zum Hauptinhalt springen

JSON key filters (SDK)

Translate only the JSON fields you want. Use keyFilters in the SDK call to include human‑visible strings (labels, headings) and exclude structural keys (ids, slugs, routes, etc.).

Quick start​

import { FrenglishSDK } from '@frenglish/sdk'

const fr = FrenglishSDK(process.env.FRENGLISH_API_KEY!)

await fr.translate(
  [JSON.stringify(myJson)],      // content array
  false,                         // full file vs. delta
  ['config.json'],               // file identifiers
  {
    keyFilters: {
      includeFilters: [
        'title', 'subtitle', 'label',
        'sections.*.heading',
      ],
      excludeFilters: [
        'id', 'slug', 'path', 'url',
        'routes', 'pages', 'keys',
      ],
    },
  }
)

Rule of thumb: Include human‑visible text; exclude keys that drive routing, lookups, or program logic.

Types (from packages/utils/src/types/configuration.ts)​

export interface Configuration {
  id: number;
  projectID: number;
  originLanguage: string | null;
  languages: string[] | null;
  languageSelector: LanguageSelector | null;
  excludedTranslationBlocks: ExcludedTranslationBlock[] | null;
  rules: string | null;
  knowledgeBaseFiles: string[];
  autoMergeToBaseBranch: boolean;
  rulesPerLanguage: Rule[] | null;
  oneTimeTranslation: boolean;
  keyFilters: Filter | null;              // ← use this
  createdAt: string | null;
  lastModifiedAt: string | null;
}

export type PartialConfiguration = Partial<Configuration>;

export interface Filter {
  includeFilters: string[] | null;
  excludeFilters: string[] | null;
}

Pass keyFilters in the per‑call PartialConfiguration argument to translate(...) or translateString(...).

Pattern syntax​

  • Paths are dot‑separated: meta.title, profile.bio.

  • * wildcard matches across segments and arrays:

    • sections.*.heading → sections[0].heading, sections[1].heading, …
    • *.meta.title → any meta.title regardless of prefix.

  • Precedence: excludeFilters win over includeFilters.

  • Conflicts: the same pattern in both lists should error.

Examples (generic)​

CMS content​

Translate author‑facing text; skip machine fields.

keyFilters: {
  includeFilters: ['fields.*.label', 'fields.*.placeholder', 'helpText'],
  excludeFilters: ['fields.*.id', 'fields.*.name', 'fields.*.key']
}

App settings​

Localize what users read; ignore technical defaults.

keyFilters: {
  includeFilters: ['settings.*.title', 'settings.*.description'],
  excludeFilters: ['settings.*.key', 'settings.*.default']
}

Keep structure intact; translate only visible labels.

keyFilters: {
  includeFilters: ['nav.*.group', 'nav.*.label'],
  excludeFilters: ['nav.*.path', 'nav.*.slug', 'nav.*.children']
}

Minimal end‑to‑end​

const raw = await fs.readFile('input.json', 'utf8')
const out = await fr.translate([raw], false, ['input.json'], {
  keyFilters: {
    includeFilters: ['*.title', '*.subtitle', '*.label'],
    excludeFilters: ['*.id', '*.slug', '*.path', '*.url']
  }
})

await fs.writeFile('output.json', out.content[0], 'utf8')

Use keyFilters to keep translations safe, predictable, and code‑review friendly.