Adding a Humanizer language

Contributor guide for adding a Humanizer locale to OpenQuok — detection, catalogs, local rewrite, UI copy, and tests.

3 min read

Connect your agent today

Draft from chat, review in your calendar, and publish only what you approve.

Overview

The OpenQuok Humanizer (/tools/humanizer) rewrites social drafts so they read less AI-written.

Adding another language means extending the locale folder under web/src/lib/ai-humanize/constants/locales/.

web/src/lib/ai-humanize/constants/locales/
  types.ts           # HumanizeLocale union — extend when adding a locale
  index.ts           # HUMANIZE_UI_COPY aggregate + re-exports
  en/                # English catalogs + localRewrite + ui + sharedContext
  th/                # Thai catalogs + localRewrite + ui + rewriterContext

What you add per locale

Topic	What contributors add
Detection	Extend localeDetect.ts — script ratio, regex, or threshold so mixed drafts route correctly
Catalogs	lexicon.ts, tells.ts, swapTable.ts, smokingGuns.ts under locales/<code>/
Local rewrite	locales/<code>/localRewrite.ts + co-located localRewrite.test.ts
Rewriter path	locales/<code>/rewriterContext.ts (or reuse EN sharedContext.ts when appropriate) + wire in buildCreateOptions.ts
UI labels	locales/<code>/ui.ts + register in uiLocale.ts and locales/index.ts
Router	Branch in localRewrite.ts so the new locale runs its cleanup function
Tests	cd web && pnpm exec vitest run src/lib/ai-humanize

Contributor checklist

Extend the locale type

Add your ISO-style code to types.ts:

export type HumanizeLocale = 'en' | 'th' | 'xx';

Use a short stable slug (th, not th-TH) — the same value appears in detection, Rewriter language tags, and folder names.

Add detection

Update localeDetect.ts so detectHumanizeLocale() returns your code when the draft matches.

Thai uses a script-ratio heuristic: more than 20% of non-whitespace characters in the Thai Unicode block (\u0E00-\u0E7F) routes to th. Mixed Thai/English brand names stay on the Thai path without sending mostly-English posts through Thai catalogs.

For a new script, prefer a measurable rule (ratio, dominant script, or a small set of locale-specific markers).

Create the locale folder and catalogs

Add web/src/lib/ai-humanize/constants/locales/<code>/ mirroring Thai:

File	Purpose
lexicon.ts	Tier-1/tier-2 stock wording → plainer stand-ins for local rewrite
tells.ts	Opener phrases, pep-talk endings, negative parallelism patterns, etc.
swapTable.ts	Phrase-level replacements (order matters — longer phrases first)
smokingGuns.ts	High-confidence stock openers to strip entirely
index.ts	Re-export the modules.

Copy structure and naming from locales/th/. Entries use shared types from writingGuide.types.ts.

Warning

English local rewrite uses word-boundary guards; Thai uses substring matching because words are not space-delimited. Match the strategy your language needs in localRewrite.ts.

Implement local rewrite + tests

Add localRewrite.ts exporting applyLocalHumanizeRewriteXx().

Co-locate localRewrite.test.ts with realistic before/after sentences: em-dash cleanup, tier-1 swaps, swap-table rows, smoking-gun drops. Thai tests live beside the locale file; English coverage is in utils/localRewrite.test.ts.

Wire the router in utils/localRewrite.ts:

return detectHumanizeLocale(source) === 'xx'
  ? applyLocalHumanizeRewriteXx(source)
  : detectHumanizeLocale(source) === 'th'
    ? applyLocalHumanizeRewriteTh(source)
    : applyLocalHumanizeRewriteEn(source, mode);

(Use a clear dispatch — switch or a small map — rather than a long ternary chain when you add a third locale.)

Wire Rewriter language settings

Add rewriterContext.ts with a compact instruction block (see Thai COMPOSER_HUMANIZE_TH_LANGUAGE_CONTEXT). Update buildCreateOptions.ts:

rewriterLanguagesFor() — set expectedInputLanguages, expectedContextLanguages, and outputLanguage for on-device Rewriter.
buildComposerHumanizeSharedContext() — append your language context when the rewrite locale matches.

English keeps using en/sharedContext.ts for Human and Roughen preambles.

Add UI copy

Create ui.ts with HUMANIZE_MODE_OPTIONS and HUMANIZE_UI_COPY (same keys as English — see en/ui.ts).

Register in:

locales/index.ts — import UI copy and add to HUMANIZE_UI_COPY.
uiLocale.ts — map browser language tags (e.g. th* → th) in detectHumanizeUiLocale(), humanizeModeOptionsFor(), and humanizeUiCopyFor().

Run tests and open a PR

cd web && pnpm exec vitest run src/lib/ai-humanize

Follow Submit a pull request here.

PR review prompts

Before opening a PR, confirm:

HumanizeLocale extended; detection has tests for edge cases.
Catalogs cover realistic AI-stock phrasing for the target language; local rewrite tests assert concrete before/after strings.
buildCreateOptions.ts sets Rewriter languages and shared context for the new locale.
ui.ts registered; browser tag mapping documented in a short comment.
utils/localRewrite.ts dispatches to the new cleanup function.