Welcome to my app
This content will be translated automatically.
Welcome to my app
This content will be translated automatically.
{gt('Hello')}
; } ```Hello, world!
Here is an image
Welcome to my app
This content will be translated automatically.
Welcome to my app
This content will be translated automatically.
{/* Your application content */}
Hello, world!
Here is an image
{/* Your application content */}
Hello, world!
Here is an image
Welcome to our app!
This content is automatically translated.
Welcome to our app!
This content is automatically translated.
Welcome to our app
Welcome to our app
; } ``` The compiler detects the translatable text and wraps it automatically at build time. User-written `{user.name} is away
} >{user.name} status unknown
You have
{isActive ? 'User is active' : 'User is inactive'}
User is inactive
} />User Dashboard
} guest={Guest Access
} >Access level unknown
Please log in
} />Enjoy your premium experience
} enterprise={Contact support for enterprise solutions
} >Subscription status unavailable
Due in
Due in
Due in
Due in
Order {order.id} shipped on
Order {order.id} was delivered successfully
} >Order status unknown
Active user
:Inactive user
}Inactive user
} />Loading...
: status === 'error' ?Error occurred
: status === 'success' ?Success!
:Unknown status
}Error occurred
} success={Success!
} >Unknown status
1 item
:{count} items
}1 item
} other={{count} items
} /> ``` ### Complex nested logic Although this works, we recommend keeping branching logic simple and avoid deep nesting: ```jsx // ❌ Complex nested branching{t('greetings.hello')}
;
}
```
### Component pattern
```tsx
// Direct component usage - recommended
function MyComponent() {
return Hello, world!
{t('greetings.hello')}
{t('greetings.welcome')}
{t('greetings.hello')}
{t('greetings.welcome')}
{t('user.greeting', { name: 'Alice' })}
{t('user.itemCount', { count: 5 })}
{t('user.orderTotal', { amount: 99.99 })}
{t('welcome')}
{/* -> dashboard.header.welcome */}{t('lastLogin', { date: 'Today' })}
{/* -> dashboard.header.lastLogin */}{t('totalUsers', { count: 1000 })}
{/* -> dashboard.stats.totalUsers */}{t('activeUsers', { count: 150 })}
{/* -> dashboard.stats.activeUsers */}
{/* Dictionary for simple strings */}
{/* Dictionary for form labels */}
);
}
```
## Next steps
{t('page.title')}
{/* T component for complex JSX */}This is a complex message with links.
{translatedMessage}
);
}
```
## Server-side only
Both [`{translated}
;
}
// ❌ Client component - won't work
'use client';
function ClientComponent() {
const translated = await tx(dynamicContent); // Error!
return {translated}
;
}
```
## Examples
### User-generated content
```jsx
import { Tx } from 'gt-next';
async function ChatMessage({ message }) {
return (
{message.author}
{translatedTitle}
{article.publishedAt}
{/* Static content with variables */}
{/* Dynamic user content */}
{review.content}
);
}
```
## API route usage
[`tx`](/docs/next/api/strings/tx) works in Next.js API route handlers, not just server components:
```tsx
// app/api/translate/route.ts
import { tx } from 'gt-next/server';
import { NextRequest, NextResponse } from 'next/server';
export async function POST(request: NextRequest) {
const { text, locale } = await request.json();
const translated = await tx(text, { locale });
return NextResponse.json({ translated });
}
```
This is useful when you need to expose translation as an API endpoint — for example, to serve client components or external services.
## Client-side translation pattern
Since [`tx`](/docs/next/api/strings/tx) is server-only, client components can translate dynamic content by calling an API route as a proxy:
```tsx
'use client';
async function translateText(text: string) {
const res = await fetch('/api/translate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ text, locale: 'fr' }),
});
const { translated } = await res.json();
return translated;
}
```
This pairs with the [API route above](#api-route-usage) to give client components access to dynamic translation.
## Translating multiple items
Use `Promise.all` to translate arrays of content in parallel:
```tsx
import { tx } from 'gt-next/server';
const translatedPosts = await Promise.all(
posts.map(async (post) => ({
...post,
title: await tx(post.title),
}))
);
```
This is useful for translating lists of database records, API responses, or any collection of dynamic strings.
## Common issues
### Avoid overuse
Don't use dynamic translation for content that can use standard components:
```jsx
// ❌ Unnecessary
const content = `Hello, ${userName}!`;
return {review.author} rated this {review.rating} stars
Hello, {userName}!
{t('hello.description')}
}
```
You'll need to replace it with:
```tsx
export default function MyComponent() {
const gt = useGT()
return {gt('Hello, world!')}
}
// OR
export default function MyComponent() {
return {t('hello.description')}
}
```
{t('hello.description')}
}
```
{m(encodedString)}
;
}
```
### Server components
Use [`getMessages`](/docs/next/api/strings/get-messages) function:
```tsx
import { getMessages } from 'gt-next/server';
const encodedString = msg('Hello, world!');
async function MyServerComponent() {
const m = await getMessages();
return {m(encodedString)}
;
}
```
## Getting original strings with decodeMsg
Sometimes you need to access the original string without translation, such as for logging, debugging, or comparisons. Use [`decodeMsg`](/docs/next/api/strings/msg) to extract the original text:
```tsx
import { decodeMsg } from 'gt-next';
const encoded = msg('Hello, world!');
const original = decodeMsg(encoded); // "Hello, world!" (original)
const translated = m(encoded); // "Hello, world!" (in user's language)
// Useful for logging or debugging
console.log('Original string:', decodeMsg(encoded));
console.log('Translated string:', m(encoded));
```
### Use cases for decodeMsg
- **Development & Debugging**: Log original strings for troubleshooting
- **Fallback Handling**: Use original text when translations fail
- **String Comparisons**: Compare against known original values
- **Analytics**: Track original string usage
```tsx
// Example: Fallback handling
function getDisplayText(encodedStr) {
const m = useMessages();
try {
return m(encodedStr);
} catch (error) {
console.warn('Translation failed, using original:', decodeMsg(encodedStr));
return decodeMsg(encodedStr);
}
}
```
## Using variables
For strings with dynamic content, use placeholders and pass variables:
```tsx
// Mark string with variables
const items = 100;
export const pricing = [
{
name: 'Basic',
price: 100,
description: msg('The basic plan includes {items} items', { items })
}
];
```
```tsx
// Use in component
function PricingCard() {
const m = useMessages();
return (
{pricing[0].name}
{m(pricing[0].description)}
{products.map(product => (
))}
);
}
```
## Common issues
### Using encoded strings directly
Never use the output of [`msg`](/docs/next/api/strings/msg) directly:
```tsx
// ❌ Wrong - encoded string used directly
const encoded = msg('Hello, world!');
return {product.name}
{m(product.description)}
{encoded}
; // Shows encoded string, not translation
// ✅ Correct - decode the string first
const encoded = msg('Hello, world!');
const m = useMessages();
return {m(encoded)}
; // Shows proper translation
```
### Dynamic content in msg()
Strings must be known at build time:
```tsx
// ❌ Wrong - dynamic template literal
const name = 'John';
const message = msg(`Hello, ${name}`); // Build time error
// ✅ Correct - use variables
const name = 'John';
const message = msg('Hello, {name}', { name });
```
### Forgetting to decode
Every [`msg`](/docs/next/api/strings/msg) string needs to be decoded:
```tsx
// ❌ Missing decoding
const config = {
title: msg('Dashboard'),
subtitle: msg('Welcome back')
};
// Later in component - forgot to decode
return {config.title}
; // Shows encoded string // ✅ Correct - decode when using const m = useMessages(); return{m(config.title)}
; // Shows translated title ``` ## Next steps - [Dictionaries Guide](/docs/next/guides/dictionaries) - Organize translations with structured data - [Languages Guide](/docs/next/guides/languages) - Configure supported languages - API References: - [`msg` Function](/docs/next/api/strings/msg) - [`useMessages` Hook](/docs/next/api/strings/use-messages) # gt-next: General Translation Next.js SDK: Static Site Generation URL: https://generaltranslation.com/en-US/docs/next/guides/ssg.mdx --- title: Static Site Generation description: Pre-render internationalized pages at build time for optimal performance --- ## Overview Static Site Generation (SSG) pre-renders pages at build time, creating static HTML files that can be served directly without server-side processing. When combined with internationalization, SSG generates pre-rendered versions for each locale.
{m(HEADING)}
),
{ width: 1200, height: 630 }
);
}
```
This also applies to `twitter-image.tsx` and any other metadata image routes.
---
## Further reading
Welcome to our store!
{product.name}
{messages.statusMessages[product.status]}
{messages.categories.find(c => c.id === product.categoryId)?.name}{gt('Featured Products')}
{gt('Check out our latest and most popular items')}
{gt(userMessage)}
; // This will fail } // ✅ Use predefined strings function MyComponent() { const [messageType, setMessageType] = useState('welcome'); const gt = useGT(); const messages = { welcome: gt('Welcome to our app!'), goodbye: gt('Thanks for visiting!') }; return{messages[messageType]}
; } ``` ### Hook rules violations Follow React hook rules when using [`useGT`](/docs/next/api/strings/use-gt): ```jsx // ❌ Don't call hooks conditionally function MyComponent({ showMessage }) { if (showMessage) { const gt = useGT(); // Hook rule violation return{gt('Hello!')}
; } return null; } // ✅ Always call hooks at top level function MyComponent({ showMessage }) { const gt = useGT(); if (showMessage) { return{gt('Hello!')}
; } return null; } ```Hello, world!
; } // After function Greeting() { returnHello, world!
Page Title
Important: Please read carefully.
Welcome to our site
Hello {username}
Today is {new Date()}
Hello {username}
Welcome
Welcome back, {user.name}!
You have
Your birthday is
Your balance is
Welcome to Our Platform
Get started in minutes with our simple setup process.
{feature.title}
{feature.description}
Welcome to Our Platform
Get started in minutes with our simple setup process.
This won't be translated
; }This will be translated
This will be translated
This will be translated
Hello {username}
Hello {username}
Welcome back, {user.name}!
You have
Balance:
Last login:
Hello {username}
Hello {username}
Hello, {user.name}!
Your account ID is {user.accountId}