next-intl-dot-notation-error

Convert flat next-intl translation keys with literal dots into nested objects.

1|Updated Jan 23, 2026

Search Tags:#migration #translation #i18n #next-intl #nesting #locales

Ready to run

npx skills add https://github.com/Hankanman/claude-config --skill next-intl-dot-notation-error

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: next-intl-dot-notation-error
Source: https://github.com/Hankanman/claude-config/tree/main/config/skills/next-intl-dot-notation-error
Command: npx skills add https://github.com/Hankanman/claude-config --skill next-intl-dot-notation-error

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

next-intl often throws INVALID_KEY when translation keys contain literal dots, which prevents app startup and breaks translations. This Skill provides a proven approach to convert flat key structures that use dots as characters into a nested object structure suitable for dot notation.

Core Features & Use Cases

Convert flat keys containing literal dots into nested objects, e.g., "email.notification.booking" -> { email: { notification: { booking: ... } } }.
Update code references to use dot notation for nested lookups (e.g., t('categories.email.notification.booking')).
Guidance for migration across locales and ensuring consistency across files.

Quick Start

Identify files with problematic keys.
Apply the transformation to create nested structures in all locale files.
Test translations load and dynamic access works.

Frequently Asked Questions about next-intl-dot-notation-error

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

Why does next-intl throw an INVALID_KEY error when my translation keys contain dots?▼

next-intl throws the INVALID_KEY error because namespace keys cannot contain the literal '.' character. You must convert flat keys like email.notification.booking into nested objects to resolve this app startup failure.

How do I convert flat translation keys to nested objects for next-intl?▼

To convert flat translation keys, transform dot-separated strings into nested structures like { email: { notification: { booking: ... } } }. You must update locale files across all locales and adopt dot notation for access.

How do I update code references when migrating to nested translation objects?▼

When migrating to nested translation objects, update code references to use dot notation for nested lookups, changing calls to match the new structure such as t('categories.email.notification.booking').

Do I need to update all locale files when migrating next-intl flat keys to nested structures?▼

Yes, migrating from flat key structures to nested objects requires updating locale files across all locales to ensure consistency. You must apply the transformation to all files before testing translation loading.

What is the best way to fix next-intl namespace keys containing literal dots?▼

The best way to fix namespace keys containing literal dots is converting flat key structures into nested objects. This proven approach resolves the INVALID_KEY error and enables dot notation access for dynamic lookups.