perf: add runtime translation functions

[bgub]

Summary

Adds a function-based generaltranslation/runtime entrypoint for runtime translation and moves framework runtime paths off the full GT class/admin client.

• add translate / translateMany runtime functions in generaltranslation/runtime
• switch gt-i18n, gt-next, gt-react, and @generaltranslation/react-core runtime code to use runtime functions, I18nConfig, or LocaleConfig instead of constructing GT
• remove the legacy getGTClass / useGTClass runtime surfaces for Odysseus
• update middleware locale resolution to use LocaleConfig

Public API Changes

Added:

• generaltranslation/runtime
  • translate
  • translateMany
  • RuntimeTranslateConfig
  • RuntimeTranslateOptions

Removed:

• gt-i18n: getGTClass
• gt-react: getGTClass, useGTClass
• gt-react-native: getGTClass, useGTClass
• gt-next: getGTClass, useGTClass
• @generaltranslation/react-core/hooks: useGTClass
• @generaltranslation/react-core/pure: getGTClass
• I18nConfig#getGTClass()

Bundle Impact

Measured earlier against ~/code/bengubler.com with pnpm next experimental-analyze --output using temporary site copies:

• client static chunks: unchanged on that app
• analyzer module count: 3347 -> 3338 (-9)
• GT-related module count: 542 -> 537 (-5)
• normal app routes: about -1.6 KiB gzip per route
• middleware: about -10.6 KiB gzip
• aggregate route analyzer gzip: about -32.6 KiB

Verification

• git diff --check
• pnpm --filter generaltranslation typecheck
• pnpm --filter generaltranslation build
• pnpm --filter generaltranslation test
• pnpm --filter gt-i18n typecheck
• pnpm --filter gt-i18n build
• pnpm --filter gt-i18n test
• pnpm --filter @generaltranslation/react-core typecheck
• pnpm --filter @generaltranslation/react-core build
• pnpm --filter @generaltranslation/react-core test
• pnpm --filter gt-react typecheck
• pnpm --filter gt-react build
• pnpm --filter gt-react test
• pnpm --filter gt-react-native typecheck
• pnpm --filter gt-next typecheck
• pnpm --filter gt-next build
• pnpm --filter gt-next test:js

Greptile Summary

Introduces a lightweight generaltranslation/runtime entrypoint with translate / translateMany functions and migrates all framework runtime paths (gt-i18n, gt-next, gt-react, gt-react-native, @generaltranslation/react-core) off the full GT class. The middleware locale resolver is also switched from GT to the smaller LocaleConfig.

• New packages/core/src/runtime.ts exports translate, translateMany, RuntimeTranslateConfig, RuntimeTranslateOptions, and re-exports all @generaltranslation/format utilities, becoming the single runtime import target.
• I18nConfig replaces getGTClass() with first-class translate(), translateMany(), and getRegionProperties() methods; the createTranslateManyFactory helper is updated to accept a plain function instead of a GT-shaped object.
• All getGTClass / useGTClass exports are removed from every framework surface as breaking changes (covered by the changeset).

Confidence Score: 4/5

The refactor is well-scoped and the removed getGTClass/useGTClass surfaces are cleanly excised across all packages; the two concerns are minor and neither blocks the core translation flow under normal operation.

The migration from the full GT class to LocaleConfig + runtime functions is consistent and the test suite passes. The translate wrapper's unchecked results[0] access and the redundant Array.isArray branch in I18nConfig.translateMany are the only non-trivial findings, both limited to the newly added code.

packages/core/src/runtime.ts (the translate bounds check) and packages/i18n/src/i18n-config/I18nConfig.ts (the duplicate translateMany branches) are worth a second look before merge.

Important Files Changed

Filename	Overview
packages/core/src/runtime.ts	New entrypoint for runtime translation; translate delegates to translateMany and returns results[0] without a bounds check, which could surface undefined to callers if the API returns an empty result.
packages/i18n/src/i18n-config/I18nConfig.ts	Removes getGTClass and adds translate, translateMany, and getRegionProperties; the translateMany implementation has two identical branches (only the Array.isArray type-guard differs), making the conditional dead code.
packages/next/src/middleware-dir/createNextMiddleware.ts	Replaces new GT({...}) with new LocaleConfig({...}) for locale validation; behaviour is equivalent since only BCP 47 validity and approve-list checks are used.
packages/next/src/middleware-dir/utils.ts	Type of gt parameter changed to LocaleConfig; all call sites updated consistently with no logic changes.
packages/i18n/src/i18n-cache/translations-manager/utils/createTranslateMany.ts	Replaces TranslateManyClient object type with a plain function type RuntimeTranslateMany; callers updated accordingly.
packages/react-core/src/hooks/useInternalRegionSelector.ts	Drops getGTClass and calls i18nConfig.getRegionProperties(r, locale) directly; locale (current user locale) is now explicitly forwarded as targetLocale, which is the intended display context.
packages/react-core/src/components/variables/Currency.shared.ts	Drops intermediate gt instance; calls getI18nConfig().formatCurrency() with an added explicit undefined for the intermediate parameter — straightforward refactor.
packages/core/package.json	Adds ./runtime export conditions (CJS + ESM) and corresponding TypeScript path mappings; follows the existing export pattern exactly.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Client / Framework Code] --> B{translate or translateMany?}
    B -->|translate| C["translate(source, options, config)"]
    B -->|translateMany| D["translateMany(sources, options, config)"]
    C --> D
    D --> E[validateRuntimeAuth\napiKey + projectId check]
    E --> F[new LocaleConfig\nsourceLocale + locales + customMapping]
    F --> G[Resolve targetLocale\nfrom options or config]
    G --> H["_translateMany(sources, resolvedOptions, config)"]
    H --> I[GT API]

    J[I18nConfig.translate] --> K["runtimeTranslate(source, options, getRuntimeTranslateConfig())"]
    K --> C
    L[I18nConfig.translateMany] --> M["runtimeTranslateMany(sources, options, getRuntimeTranslateConfig())"]
    M --> D

    N[Middleware] --> O[new LocaleConfig\nfrom envParams]
    O --> P["localeConfig.isValidLocale()\nlocaleConfig.determineLocale()"]
    P --> Q[Locale resolution\n& routing]

    R[Component Variables\nCurrency/DateTime/Num/RelativeTime] --> S["getI18nConfig().formatXxx()"]
    S --> T[LocaleConfig formatting methods]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Client / Framework Code] --> B{translate or translateMany?}
    B -->|translate| C["translate(source, options, config)"]
    B -->|translateMany| D["translateMany(sources, options, config)"]
    C --> D
    D --> E[validateRuntimeAuth\napiKey + projectId check]
    E --> F[new LocaleConfig\nsourceLocale + locales + customMapping]
    F --> G[Resolve targetLocale\nfrom options or config]
    G --> H["_translateMany(sources, resolvedOptions, config)"]
    H --> I[GT API]

    J[I18nConfig.translate] --> K["runtimeTranslate(source, options, getRuntimeTranslateConfig())"]
    K --> C
    L[I18nConfig.translateMany] --> M["runtimeTranslateMany(sources, options, getRuntimeTranslateConfig())"]
    M --> D

    N[Middleware] --> O[new LocaleConfig\nfrom envParams]
    O --> P["localeConfig.isValidLocale()\nlocaleConfig.determineLocale()"]
    P --> Q[Locale resolution\n& routing]

    R[Component Variables\nCurrency/DateTime/Num/RelativeTime] --> S["getI18nConfig().formatXxx()"]
    S --> T[LocaleConfig formatting methods]

Loading

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
packages/core/src/runtime.ts:67-68
The `translate` wrapper returns `results[0]` directly. If `_translateMany` ever produces an empty array (e.g., a malformed API response), callers receive `undefined` at runtime despite the declared return type of `TranslationResult | TranslationError`. A guard here prevents a silent type violation from propagating.

```suggestion
  const results = await translateMany([source], options, config, timeout);
  if (!results[0]) {
    throw new Error('translate: no result returned for the provided source');
  }
  return results[0];
```

### Issue 2 of 2
packages/i18n/src/i18n-config/I18nConfig.ts:160-179
Both branches of the `Array.isArray` guard call `runtimeTranslateMany` with the same arguments — the conditional is dead code. The `runtimeTranslateMany` implementation already accepts `TranslateManyEntry[] | Record<string, TranslateManyEntry>`, so TypeScript overload resolution handles the type narrowing without any runtime branching.

```suggestion
  async translateMany(
    sources: TranslateManyEntry[] | Record<string, TranslateManyEntry>,
    options: RuntimeTranslateOptions,
    timeout?: number
  ): Promise<TranslateManyResult | Record<string, TranslationResult>> {
    return await runtimeTranslateMany(
      sources as TranslateManyEntry[],
      options,
      this.getRuntimeTranslateConfig(),
      timeout
    );
  }
```

_{Reviews (1): Last reviewed commit: "perf: add runtime translation functions" | Re-trigger Greptile}

Greptile also left 2 inline comments on this PR.

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Middleware Benchmarks'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.50.

Benchmark suite	Current: 1fc3256	Previous: c1ad1f7	Ratio
gt-next > e2e > middleware: redirect-chain-fr-about > elapsed	669 ms	128 ms	5.23
gt-next > e2e > middleware: redirect-chain-fr-about > ttfb	575.5999999999767 ms	17.29999999998836 ms	33.27
gt-next > e2e > middleware: redirect-chain-fr-about > domContentLoaded	585 ms	26.39999999999418 ms	22.16
gt-next > e2e > middleware: redirect-chain-fr-about > load	661 ms	119.29999999998836 ms	5.54

This comment was automatically generated by workflow using github-action-benchmark.

CC: @generaltranslation/core

[greptile-apps]

The translate wrapper returns results[0] directly. If _translateMany ever produces an empty array (e.g., a malformed API response), callers receive undefined at runtime despite the declared return type of TranslationResult | TranslationError. A guard here prevents a silent type violation from propagating.

Suggested change

	const results = await translateMany([source], options, config, timeout);
	return results[0];
	const results = await translateMany([source], options, config, timeout);
	if (!results[0]) {
	throw new Error('translate: no result returned for the provided source');
	}
	return results[0];

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/core/src/runtime.ts
Line: 67-68

Comment:
The `translate` wrapper returns `results[0]` directly. If `_translateMany` ever produces an empty array (e.g., a malformed API response), callers receive `undefined` at runtime despite the declared return type of `TranslationResult | TranslationError`. A guard here prevents a silent type violation from propagating.

```suggestion
  const results = await translateMany([source], options, config, timeout);
  if (!results[0]) {
    throw new Error('translate: no result returned for the provided source');
  }
  return results[0];
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Both branches of the Array.isArray guard call runtimeTranslateMany with the same arguments — the conditional is dead code. The runtimeTranslateMany implementation already accepts TranslateManyEntry[] | Record<string, TranslateManyEntry>, so TypeScript overload resolution handles the type narrowing without any runtime branching.

Suggested change

	async translateMany(
	sources: TranslateManyEntry[] | Record<string, TranslateManyEntry>,
	options: RuntimeTranslateOptions,
	timeout?: number
	): Promise<TranslateManyResult | Record<string, TranslationResult>> {
	if (Array.isArray(sources)) {
	return await runtimeTranslateMany(
	sources,
	options,
	this.getRuntimeTranslateConfig(),
	timeout
	);
	}
	return await runtimeTranslateMany(
	sources,
	options,
	this.getRuntimeTranslateConfig(),
	timeout
	);
	}
	async translateMany(
	sources: TranslateManyEntry[] | Record<string, TranslateManyEntry>,
	options: RuntimeTranslateOptions,
	timeout?: number
	): Promise<TranslateManyResult | Record<string, TranslationResult>> {
	return await runtimeTranslateMany(
	sources as TranslateManyEntry[],
	options,
	this.getRuntimeTranslateConfig(),
	timeout
	);
	}

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/i18n/src/i18n-config/I18nConfig.ts
Line: 160-179

Comment:
Both branches of the `Array.isArray` guard call `runtimeTranslateMany` with the same arguments — the conditional is dead code. The `runtimeTranslateMany` implementation already accepts `TranslateManyEntry[] | Record<string, TranslateManyEntry>`, so TypeScript overload resolution handles the type narrowing without any runtime branching.

```suggestion
  async translateMany(
    sources: TranslateManyEntry[] | Record<string, TranslateManyEntry>,
    options: RuntimeTranslateOptions,
    timeout?: number
  ): Promise<TranslateManyResult | Record<string, TranslationResult>> {
    return await runtimeTranslateMany(
      sources as TranslateManyEntry[],
      options,
      this.getRuntimeTranslateConfig(),
      timeout
    );
  }
```

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!