GitHub

Dynamic content translation handles text that isn't available at build time - user-generated content, API responses, or database records. Use <Tx> for JSX content and tx for plain strings, both server-side only for security.

Use sparingly: Dynamic translation consumes API quota and adds latency. Prefer <T> components with variable components whenever possible.

When to Use Dynamic Translation

Dynamic translation is for content that truly cannot be known at build time:

Appropriate Use Cases

User-generated content: Chat messages, reviews, social posts
External API responses: Third-party data, RSS feeds, external services
Database records: Dynamic CMS content, user profiles from APIs
Real-time data: Live notifications, status messages

Avoid for These Cases

User names, account numbers → Use <Var>
Conditional messages → Use branch components
Form validation → Use string translation
Static configuration → Use shared strings

Quick Start

JSX Content with `<Tx>`

import { Tx } from 'gt-next';

async function UserPost({ postContent }) {
  return (
    <article>
      <Tx>{postContent}</Tx>
    </article>
  );
}

Plain Strings with `tx`

import { tx } from 'gt-next/server';

async function NotificationBanner({ message }) {
  const translatedMessage = await tx(message);
  
  return (
    <div className="banner">
      {translatedMessage}
    </div>
  );
}

Server-Side Only

Both <Tx> and tx are server-side only for security:

// ✅ Server component
async function ServerComponent() {
  const translated = await tx(dynamicContent);
  return <div>{translated}</div>;
}

// ❌ Client component - won't work
'use client';
function ClientComponent() {
  const translated = await tx(dynamicContent); // Error!
  return <div>{translated}</div>;
}

Examples

User-Generated Content

import { Tx } from 'gt-next';

async function ChatMessage({ message }) {
  return (
    <div className="chat-message">
      <div className="author">{message.author}</div>
      <Tx>{message.content}</Tx>
    </div>
  );
}

External API Data

import { tx } from 'gt-next/server';

async function NewsArticle({ article }) {
  const translatedTitle = await tx(article.title);
  
  return (
    <article>
      <h1>{translatedTitle}</h1>
      <p>{article.publishedAt}</p>
    </article>
  );
}

Mixed Content

import { T, Tx, Var } from 'gt-next';

async function ProductReview({ review }) {
  return (
    <div>
      {/* Static content with variables */}
      <T>
        <p><Var>{review.author}</Var> rated this <Var>{review.rating}</Var> stars</p>
      </T>
      
      {/* Dynamic user content */}
      <Tx>{review.content}</Tx>
    </div>
  );
}

Common Issues

Avoid Overuse

Don't use dynamic translation for content that can use standard components:

// ❌ Unnecessary
const content = `Hello, ${userName}!`;
return <Tx>{content}</Tx>;

// ✅ Use variable components instead
return (
  <T>
    <p>Hello, <Var>{userName}</Var>!</p>
  </T>
);

API Quota Impact

Dynamic translation consumes API quota on every request. Use caching and error handling in production applications.

Next Steps

Local Translation Guide - Handle translations without API calls
Middleware Guide - Language detection and routing
API References:
- <Tx> Component

Use sparingly: Dynamic translation consumes API quota and adds latency. Prefer <T> components with variable components whenever possible.

When to Use Dynamic Translation

Dynamic translation is for content that truly cannot be known at build time:

Appropriate Use Cases

User-generated content: Chat messages, reviews, social posts
External API responses: Third-party data, RSS feeds, external services
Database records: Dynamic CMS content, user profiles from APIs
Real-time data: Live notifications, status messages

Avoid for These Cases

User names, account numbers → Use <Var>
Conditional messages → Use branch components
Form validation → Use string translation
Static configuration → Use shared strings

Quick Start

JSX Content with `<Tx>`

import { Tx } from 'gt-next';

async function UserPost({ postContent }) {
  return (
    <article>
      <Tx>{postContent}</Tx>
    </article>
  );
}

Plain Strings with `tx`

import { tx } from 'gt-next/server';

async function NotificationBanner({ message }) {
  const translatedMessage = await tx(message);
  
  return (
    <div className="banner">
      {translatedMessage}
    </div>
  );
}

Server-Side Only

Both <Tx> and tx are server-side only for security:

// ✅ Server component
async function ServerComponent() {
  const translated = await tx(dynamicContent);
  return <div>{translated}</div>;
}

// ❌ Client component - won't work
'use client';
function ClientComponent() {
  const translated = await tx(dynamicContent); // Error!
  return <div>{translated}</div>;
}

Examples

User-Generated Content

import { Tx } from 'gt-next';

async function ChatMessage({ message }) {
  return (
    <div className="chat-message">
      <div className="author">{message.author}</div>
      <Tx>{message.content}</Tx>
    </div>
  );
}

External API Data

import { tx } from 'gt-next/server';

async function NewsArticle({ article }) {
  const translatedTitle = await tx(article.title);
  
  return (
    <article>
      <h1>{translatedTitle}</h1>
      <p>{article.publishedAt}</p>
    </article>
  );
}

Mixed Content

import { T, Tx, Var } from 'gt-next';

async function ProductReview({ review }) {
  return (
    <div>
      {/* Static content with variables */}
      <T>
        <p><Var>{review.author}</Var> rated this <Var>{review.rating}</Var> stars</p>
      </T>
      
      {/* Dynamic user content */}
      <Tx>{review.content}</Tx>
    </div>
  );
}

Common Issues

Avoid Overuse

Don't use dynamic translation for content that can use standard components:

// ❌ Unnecessary
const content = `Hello, ${userName}!`;
return <Tx>{content}</Tx>;

// ✅ Use variable components instead
return (
  <T>
    <p>Hello, <Var>{userName}</Var>!</p>
  </T>
);

API Quota Impact

Dynamic translation consumes API quota on every request. Use caching and error handling in production applications.

Next Steps

Local Translation Guide - Handle translations without API calls
Middleware Guide - Language detection and routing
API References:
- <Tx> Component

Use sparingly: Dynamic translation consumes API quota and adds latency. Prefer <T> components with variable components whenever possible.

When to Use Dynamic Translation

Dynamic translation is for content that truly cannot be known at build time:

Appropriate Use Cases

User-generated content: Chat messages, reviews, social posts
External API responses: Third-party data, RSS feeds, external services
Database records: Dynamic CMS content, user profiles from APIs
Real-time data: Live notifications, status messages

Avoid for These Cases

User names, account numbers → Use <Var>
Conditional messages → Use branch components
Form validation → Use string translation
Static configuration → Use shared strings

Quick Start

JSX Content with `<Tx>`

import { Tx } from 'gt-next';

async function UserPost({ postContent }) {
  return (
    <article>
      <Tx>{postContent}</Tx>
    </article>
  );
}

Plain Strings with `tx`

import { tx } from 'gt-next/server';

async function NotificationBanner({ message }) {
  const translatedMessage = await tx(message);
  
  return (
    <div className="banner">
      {translatedMessage}
    </div>
  );
}

Server-Side Only

Both <Tx> and tx are server-side only for security:

// ✅ Server component
async function ServerComponent() {
  const translated = await tx(dynamicContent);
  return <div>{translated}</div>;
}

// ❌ Client component - won't work
'use client';
function ClientComponent() {
  const translated = await tx(dynamicContent); // Error!
  return <div>{translated}</div>;
}

Examples

User-Generated Content

import { Tx } from 'gt-next';

async function ChatMessage({ message }) {
  return (
    <div className="chat-message">
      <div className="author">{message.author}</div>
      <Tx>{message.content}</Tx>
    </div>
  );
}

External API Data

import { tx } from 'gt-next/server';

async function NewsArticle({ article }) {
  const translatedTitle = await tx(article.title);
  
  return (
    <article>
      <h1>{translatedTitle}</h1>
      <p>{article.publishedAt}</p>
    </article>
  );
}

Mixed Content

import { T, Tx, Var } from 'gt-next';

async function ProductReview({ review }) {
  return (
    <div>
      {/* Static content with variables */}
      <T>
        <p><Var>{review.author}</Var> rated this <Var>{review.rating}</Var> stars</p>
      </T>
      
      {/* Dynamic user content */}
      <Tx>{review.content}</Tx>
    </div>
  );
}

Common Issues

Avoid Overuse

Don't use dynamic translation for content that can use standard components:

// ❌ Unnecessary
const content = `Hello, ${userName}!`;
return <Tx>{content}</Tx>;

// ✅ Use variable components instead
return (
  <T>
    <p>Hello, <Var>{userName}</Var>!</p>
  </T>
);

API Quota Impact

Dynamic translation consumes API quota on every request. Use caching and error handling in production applications.

Next Steps

Local Translation Guide - Handle translations without API calls
Middleware Guide - Language detection and routing
API References:
- <Tx> Component

Dynamic Content

On this page

Dynamic Content

On this page

Dynamic Content

On this page