Guides
Internationalization Guide

Internationalization Guide

Provide a localized authentication experience by customizing your login pages and email templates in multiple languages. Users will automatically see content in their preferred language based on their browser settings.

Overview

Skycloak’s internationalization feature allows you to:

  • Customize login pages in 18 languages
  • Localize email templates for all notification types
  • Automatically display content based on user’s browser locale
  • Allow users to manually switch languages using a built-in language selector
  • Maintain consistent branding across all languages

Plan Requirement: Launch plan or higher

Supported Languages

Skycloak supports 18 languages with full Keycloak integration:

  • English (en) - Default
  • German (de)
  • Spanish (es)
  • French (fr)
  • Italian (it)
  • Japanese (ja)
  • Korean (ko)
  • Portuguese (Brazil) (pt-BR)
  • Russian (ru)
  • Chinese (Simplified) (zh-CN)
  • Dutch (nl)
  • Polish (pl)
  • Turkish (tr)
  • Swedish (sv)
  • Czech (cs)
  • Danish (da)
  • Norwegian (no)
  • Finnish (fi)

Setting Up Localized Login Pages

Step 1: Access Branding Settings

  1. Navigate to your realm’s settings
  2. Go to Branding tab
  3. Click on Internationalization section

Step 2: Add a New Language

  1. Click Add Language
  2. Select a language from the dropdown
  3. The form will show all customizable text fields

Step 3: Customize Login Page Text

Configure the following elements for your selected language:

Page Title

The browser tab title shown when users visit the login page.

Example:

  • English: “Login to Your Account”
  • Spanish: “Iniciar sesión en tu cuenta”
  • French: “Connexion à votre compte”

Welcome Message

The main heading displayed on the login page.

Example:

  • English: “Welcome back!”
  • Spanish: “¡Bienvenido de nuevo!”
  • French: “Bienvenue!”

Form Labels

Customize labels for form fields:

  • Username Label: “Username”, “Email”, or “Email Address”
  • Username Placeholder: Hint text in the username field
  • Password Label: “Password”, “Your Password”, etc.
  • Password Placeholder: Hint text in the password field
  • Remember Me: Checkbox label for persistent sessions

Action Buttons and Links

  • Login Button Text: Primary action button (e.g., “Sign In”, “Log In”)
  • Forgot Password Link: Link text for password recovery
  • Register Link: Link text for new user registration
  • Back to Application: Link text to return to the application

Step 4: Preview and Save

  1. Click Preview to see your changes in a live preview
  2. Click Save to store your localized content
  3. Repeat for additional languages

Configuring the Language Selector

Skycloak provides a built-in language selector that allows users to manually switch between languages on your login pages. This selector works alongside automatic browser detection to give users full control over their language preference.

Enabling the Language Selector

  1. Navigate to your realm’s Branding settings
  2. Go to Internationalization section
  3. Toggle Enable Multi-Language Support
  4. Select the languages you want to support from the language grid

The language selector will appear on all login and authentication pages, allowing users to switch between your selected languages instantly.

Language Selector Position

Choose where the language selector appears on your login pages:

Top Right (Default)

┌─────────────────────────────────┐
│                        [EN ▼]   │
│         Login Page              │
│                                 │
└─────────────────────────────────┘
  • Best for: Most layouts
  • User familiarity: Common pattern for language selectors
  • Works well with: Logos positioned on the left

Top Left

┌─────────────────────────────────┐
│ [EN ▼]                          │
│         Login Page              │
│                                 │
└─────────────────────────────────┘
  • Best for: Centered or right-aligned logos
  • Visibility: Prominent for left-to-right readers
  • Works well with: Minimalist designs

Top Middle

┌─────────────────────────────────┐
│           [EN ▼]                │
│         Login Page              │
│                                 │
└─────────────────────────────────┘
  • Best for: Centered layouts with logo at top
  • Balance: Centered attention
  • Works well with: Symmetric designs

Language Selector Styles

Choose how the language selector is displayed:

Dropdown (Recommended for 3+ languages)

  • Shows current language with dropdown arrow
  • Compact and clean interface
  • Scales well for many languages
  • Example: English ▼ → Click to see full list

Text Labels (Best for 2 languages)

  • Shows all languages as clickable text
  • Simple and direct
  • Example: EN | FR
  • Works well for bilingual sites (e.g., English/French in Canada)

Flag Icons

  • Shows country flags for each language
  • Visual and internationally recognizable
  • Example: 🇬🇧 🇫🇷 🇩🇪
  • Best for: Sites with clear country associations

Language Selection Modes

Control how language is determined for users:

Automatic + Manual Selector (Recommended)

  • Automatically detects browser language on first visit
  • Displays selector for manual override
  • Best user experience: automatic with choice
  • Use when: You want to serve users their preferred language while allowing customization

Automatic Only

  • Detects browser language automatically
  • No visible selector shown
  • Users get appropriate language without choosing
  • Use when: You have confidence in browser detection and want minimal UI

Manual Selector Only

  • Always shows selector
  • No automatic detection
  • Users must explicitly choose language
  • Use when: Browser detection is unreliable for your audience

Hide Selector (Force Default)

  • Always uses your default locale
  • No automatic detection, no selector
  • Single language experience
  • Use when: You only support one language effectively

Configuration Example

Here’s how to set up a bilingual English/French site with manual language selection:

  1. Enable Multi-Language Support
  2. Select languages: English (EN) and French (FR)
  3. Set default locale: English
  4. Choose selector style: Text Labels (shows EN | FR)
  5. Choose position: Top Right
  6. Choose mode: Automatic + Manual Selector

Result: Users see EN | FR in top right, browser language auto-detected, can manually switch anytime.

Setting Up Localized Emails

Email templates are automatically available in all languages enabled in your Branding settings. When you enable internationalization and select supported languages for login pages, those same languages become available for email templates.

How Email Localization Works

  1. Automatic Language Sync: Email languages are automatically synchronized with your branding configuration
  2. Built-in Translations: Keycloak provides built-in translations for common email templates (password reset, email verification, etc.)
  3. Language Preview: The email configuration page includes a language selector to preview how emails appear in different languages
  4. Automatic Language Detection: Users receive emails in their preferred language based on their browser/account settings

Previewing Email Languages

  1. Navigate to your realm’s Email configuration page
  2. Click the Email Templates tab
  3. Use the language dropdown in the preview panel to switch between languages
  4. Preview all three email types:
    • Password Reset
    • Email Verification
    • Test Email
  5. The preview updates instantly to show translated content

Customizing Email Appearance

While email text is automatically translated by Keycloak, you can customize the visual appearance:

Company Branding

  • Primary Color: Used for buttons and links in emails
  • Header Logo: Your company logo displayed at the top of emails
  • Company Name: Displayed in email footers
  • Footer Text: Custom footer text with copyright or legal information

Note: Email content (subject lines, body text, button labels) is automatically translated by Keycloak based on the user’s language preference. The preview shows how this content appears in each supported language.

How Language Selection Works

Skycloak provides flexible language selection combining automatic detection with optional manual control. Depending on your configuration, users can experience automatic language detection, manual selection, or both.

Automatic Detection

When enabled and a user visits your login page:

  1. Browser Locale Detection: Skycloak reads the Accept-Language header from the user’s browser
  2. Locale Matching: System matches browser preference to your supported languages
  3. Fallback Chain: If content isn’t available in their language, it falls back to:
    • The default language for your realm
    • English as the final fallback
  4. Session Persistence: Selected language is remembered for the session

Manual Language Selector

When the language selector is visible:

  1. User Override: Users can click the selector and choose their preferred language
  2. Instant Switch: Page refreshes immediately in the selected language
  3. Cookie Storage: Choice is stored in a browser cookie (KEYCLOAK_LOCALE)
  4. Persistent Preference: Selection persists across sessions until manually changed

Combined Behavior

With “Automatic + Manual Selector” mode (recommended):

  1. First visit: Browser language is automatically detected
  2. User sees content in their browser’s language (if supported)
  3. Language selector is visible for manual override
  4. User can switch at any time, overriding automatic detection
  5. Manual selection takes precedence over browser settings

Locale Priority Examples

Example 1: Spanish-speaking user with browser set to es-MX

  1. Automatic detection selects es (Spanish)
  2. User sees login page in Spanish
  3. Can manually switch to another language using selector

Example 2: User in French Canada with fr-CA browser setting

  1. Automatic detection selects fr (French)
  2. User sees content in French
  3. Can switch to English using EN | FR selector

Example 3: Browser language not supported

  1. Browser is set to he (Hebrew - not supported)
  2. Falls back to realm default (e.g., English)
  3. User can manually select from available languages

Best Practices

Translation Quality

  1. Professional Translation: Use professional translation services for customer-facing content
  2. Native Speakers: Have native speakers review translations for natural flow
  3. Cultural Sensitivity: Consider cultural differences in tone and messaging
  4. Consistency: Maintain consistent terminology across all languages

Content Guidelines

  1. Keep It Concise: Shorter text translates better and fits better in UI
  2. Avoid Idioms: Phrases that don’t translate well across cultures
  3. Test Placeholders: Ensure variable substitutions work correctly
  4. Link Validation: Verify all links work in all languages

Technical Considerations

  1. Character Encoding: All content is UTF-8 encoded for proper display
  2. RTL Languages: Currently, right-to-left languages (Arabic, Hebrew) are not fully supported
  3. Text Length: Some languages require more space (German tends to be longer)
  4. Special Characters: Test special characters display correctly in emails
  5. Language Selector Responsiveness: Selector adapts to mobile devices automatically

Testing Localized Content

Testing Login Pages

  1. Browser Language: Change your browser’s language settings to test automatic detection

    • Chrome: Settings → Languages → Add languages → Move desired language to top
    • Firefox: Preferences → Language and Appearance → Choose → Set order
    • Safari: Preferences → Advanced → Language

  2. Language Selector: Test the manual language selector directly

    • Visit your login page
    • Click the language selector (top-right, top-left, or top-middle depending on configuration)
    • Select each of your 18 supported languages
    • Verify the page refreshes in the selected language
    • Check that selection persists across page reloads

  3. URL Parameter: Add ?kc_locale= to login URL to force a specific locale

    # Test Spanish
https://your-realm.skycloak.app/auth/realms/your-realm/protocol/openid-connect/auth?kc_locale=es

# Test Japanese
?kc_locale=ja

# Test Portuguese (Brazil)
?kc_locale=pt-BR

# Test Chinese (Simplified)
?kc_locale=zh-CN

  4. Preview Mode: Use the in-dashboard preview panel

    • Switch between all 18 languages using the language dropdown
    • Verify layout works for longer German text
    • Check CJK characters display correctly (Japanese, Korean, Chinese)
    • Test special characters in European languages (ñ, é, ü, etc.)

  5. Mobile Testing: Test selector on mobile devices

    • Verify selector is accessible and clickable
    • Check dropdown menu displays correctly
    • Test on both portrait and landscape orientations

Testing Emails

  1. Email Preview Language Selector:

    • Navigate to the Email configuration page
    • Switch between languages using the language dropdown in the preview panel
    • Preview shows translated content for Password Reset, Email Verification, and Test Email templates
    • All 18 supported languages can be previewed without sending actual emails
    • Preview content uses standard translations; actual emails use Keycloak’s built-in translations

  2. Test Email Feature: Use the “Send Test Email” button to send actual emails in different languages

  3. Change User Locale: Update a test user’s locale in User Management to test automatic language detection

  4. Email Client Testing: Verify rendering in popular email clients (Gmail, Outlook, Apple Mail)

  5. Character Encoding: Ensure special characters display correctly across all 18 languages

Updating Translations

Modifying Existing Translations

  1. Navigate to Branding/Email → Internationalization
  2. Click on the language you want to modify
  3. Update the text fields
  4. Click Save & Deploy to apply changes immediately

Deployment Process

When you save changes:

  1. Content is saved to the database
  2. Theme files are regenerated with new translations
  3. Updated theme is deployed to your Keycloak cluster
  4. Changes are live within 30-60 seconds

Removing Languages

To remove a language:

  1. Navigate to Branding/Email → Internationalization
  2. Find the language you want to remove
  3. Click Delete (trash icon)
  4. Confirm deletion

Note: Deleting English (default language) is not allowed.

Troubleshooting

Content Not Displaying in Expected Language

Problem: User sees English instead of their language

Solutions:

  • Verify the language is fully configured and saved
  • Check that the user’s browser is set to the correct language
  • Confirm theme deployment completed successfully
  • Clear browser cache and reload the login page

Variables Not Replacing in Emails

Problem: Seeing ${user.firstName} instead of actual name

Solutions:

  • Verify variable syntax is exact (case-sensitive)
  • Ensure user profile has the required fields populated
  • Check for extra spaces around variable names

Text Overflowing or Cut Off

Problem: Translated text doesn’t fit in the UI

Solutions:

  • Shorten the translated text while maintaining meaning
  • Test all languages in the preview
  • Consider different translations that are more concise

Character Display Issues

Problem: Special characters showing as � or boxes

Solutions:

  • Ensure content is saved with UTF-8 encoding
  • Test special characters before full rollout
  • Verify email client supports UTF-8

Analytics and Insights

Track how users interact with localized content:

  1. Navigate to Analytics dashboard
  2. View locale usage breakdown
  3. See which languages are most common among your users
  4. Identify languages that might need better translation

Metrics available:

  • Login page views by locale
  • Email open rates by language
  • User distribution by browser language
  • Locale-specific conversion rates

API Access

For automated translation workflows, use the Skycloak API:

Get Available Locales 

GET /api/branding/i18n/available-locales

Get All Translations 

GET /api/branding/{brandingConfigID}/i18n

Add/Update Translation 

PUT /api/branding/{brandingConfigID}/i18n/{locale}
Content-Type: application/json

{
  "page_title": "Iniciar sesión",
  "welcome_message": "¡Bienvenido!",
  ...
}

Delete Translation 

DELETE /api/branding/{brandingConfigID}/i18n/{locale}

Contact support for API access details.

Frequently Asked Questions

Can I add more languages than the 18 supported?

Currently, Skycloak supports 18 languages with full Keycloak integration. Additional languages may be added in future releases based on customer demand. If you need a language not currently supported, please contact support to discuss your requirements.

How do I change the default fallback language?

You can set any supported language as your realm’s default language. Navigate to Branding → Internationalization, select your desired default language from the supported locales, and click “Set Default”. This language will be used when a user’s browser language isn’t available, before falling back to English.

Can users manually select their language?

Yes! Skycloak provides a built-in language selector with multiple display styles (dropdown, text labels, or flag icons) and positioning options (top-right, top-left, or top-middle). You can configure the selector to work alongside automatic detection or on its own. See the “Configuring the Language Selector” section above for details.

What’s the difference between the language selector styles?

  • Dropdown: Shows current language with a dropdown menu. Best for 3+ languages. Compact and scalable.
  • Text Labels: Shows all languages as clickable text (e.g., “EN | FR”). Best for 2 languages. Simple and direct.
  • Flag Icons: Shows country flags for each language. Visual and internationally recognizable. Best when languages have clear country associations.

When should I hide the language selector?

Use “Hide Selector” mode when:

  • You only effectively support one language
  • You want to force all users to see a specific language
  • Your audience is homogeneous and doesn’t need language choice
  • You want to simplify the UI by removing the selector

Do translations apply to error messages?

Yes, Keycloak’s built-in error messages will automatically display in the user’s selected language. This includes validation errors, authentication failures, and system messages. All error messages benefit from Keycloak’s native i18n support.

What happens if I don’t provide a translation?

The system uses a fallback chain:

  1. First tries the user’s selected/detected language
  2. Falls back to your realm’s default language
  3. Finally falls back to English

Users will see content, but it may not be in their preferred language. For the best experience, provide translations for all languages you enable.

How does the language selector work on mobile devices?

The language selector is fully responsive and adapts automatically to mobile devices. The dropdown is touch-optimized, and the positioning (top-right, top-left, or top-middle) adjusts to ensure it’s always accessible on smaller screens.

Next Steps

Related Resources

Attribute MappingSIEM Integration Guide