Skip to main content

Source Language Preparation

Check, clean and prepare source-language content before a run carries it into every target language. kapi runs these checks locally and in CI.

Why fix the source first​

A misspelled term, an inconsistent placeholder format or a missing sentence boundary in the source reappears in every target language. A fix in the source is one fix instead of one per language.

Common source problems:

  • Inconsistent terms: the same concept called different things in different files
  • Placeholder errors: mismatched or malformed variables (for example %s vs %d mismatch)
  • Whitespace issues: trailing spaces, mixed line endings, zero-width characters
  • Length problems: strings too long for UI constraints
  • Missing translations: source strings without corresponding target entries

Checks on Source Content​

Run quality checks directly on source files without any server connection:

# Run the rule-based checks on source content
kapi exec qa -i src/locales/en/ --source-lang en

# Check the source against the terms store's forbidden and retired terms
kapi check src/locales/en/ --termstore product-terms

# Validate XML/HTML structure in source strings
kapi xml-validation -i src/locales/en/

Built-In Rules​

The qa tool validates:

RuleWhat It Checks
whitespaceLeading/trailing whitespace, double spaces, mixed line endings
punctuationMissing or mismatched sentence-ending punctuation
placeholdersPlaceholder format consistency and completeness
terminologyRequired terms present and correctly used
lengthString length within configured limits
patternsCustom regex patterns (for example brand name capitalization)
charactersInvalid or unexpected Unicode characters

Example Flows for Source Prep​

Term Consistency Check​

Create flows/source-checks.yaml, with flows_dir: flows in kapi.yaml:

Step config keys are the tool's own schema keys, in camelCase; see the tool reference. kapi ignores an unrecognized key without an error, so a misspelled key silently drops its check. The locale comes from the run's --target-lang, so one flow serves every locale.

name: source-checks
description: Validate source content quality before translation

steps:
  - tool: term-check
    config:
      caseSensitive: true

  - tool: placeholder-check
    config:
      flagExtra: true

  - tool: qa
    config:
      checkDoubleSpaces: true
      checkDoubledWord: true
      checkPatterns: true
      checkTargetInconsistency: true

Run it, then gate on the findings. The flow annotates the content, and kapi check turns the findings into an exit code:

kapi run source-checks --target-lang fr
kapi check src/locales/en/*.json --target src/locales/fr/app.json \
  --target-lang fr

The command exits non-zero when a finding fails; advisory findings are reported and fail nothing.

Scoping and Content Stats​

Before starting a project, analyze the source content:

# Content stats (blocks, words, characters) across all source files
kapi stats src/locales/en/*.json

# Memory reuse, remaining work, and token estimate for the pending locales
kapi up --plan

Cleanup​

case-transform normalizes the source; whitespace-correct tidies the target against it, so it runs after a target exists. Step config keys are camelCase, the same spelling as the tool's schema, which the tool reference lists.

name: cleanup
description: Normalize source case, then tidy the target's whitespace

steps:
  - tool: case-transform
    config:
      mode: title
      applySource: true

  - tool: whitespace-correct
    config:
      normalizeSpaces: true
      matchSourceWhitespace: true
      removeZeroWidthChars: true

CI Integration​

Pre-Push Check Gate​

Add the source checks to your CI pipeline so content that fails validation never reaches the server. Declare local automation rules at the top level of your kapi.yaml recipe:

automations:
  - name: checks-before-push
    trigger: pre-push
    actions:
      - type: run_flow
        config:
          flow: source-checks
          fail_on_error: true

GitHub Actions​

Run the source checks on every pull request that modifies content files:

name: Source checks

on:
  pull_request:
    paths:
      - "src/locales/en/**"

jobs:
  source-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: neokapi/setup-kapi@v1
        with:
          version: "1.2.0"
          plugins: bowrain@1.2.0

      - name: Run the source checks
        run: kapi run source-checks

      - name: Content stats report
        run: kapi stats src/locales/en/*.json --json

This catches source-language issues at the PR stage, before they propagate to translations.