fix: Improve warning for invalid namespace characters

packages/use-intl/src/core/validateMessages.tsx

@@ -34,9 +34,43 @@ export default function validateMessages(
     onError(
       new IntlError(
         IntlErrorCode.INVALID_KEY,
-        `Namespace keys can not contain the character "." as this is used to express nesting. Please remove it or replace it with another character.\n\nInvalid ${
-          invalidKeyLabels.length === 1 ? 'key' : 'keys'
-        }: ${invalidKeyLabels.join(', ')}`
+        process.env.NODE_ENV !== 'production'
+          ? `Namespace keys can not contain the character "." as this is used to express nesting. Please remove it or replace it with another character.
+
+Invalid ${
+              invalidKeyLabels.length === 1 ? 'key' : 'keys'
+            }: ${invalidKeyLabels.join(', ')}
+
+If you're migrating from a flat structure, you can convert your messages as follows:
+
+import {set} from "lodash";
+
+const input = {
+  "one.one": "1.1",
+  "one.two": "1.2",
+  "two.one.one": "2.1.1"
+};
+
+const output = Object.entries(input).reduce(
+  (acc, [key, value]) => set(acc, key, value),
+  {}
+);
+
+// Output:
+//
+// {
+//   "one": {
+//     "one": "1.1",
+//     "two": "1.2"
+//   },
+//   "two": {
+//     "one": {
+//       "one": "2.1.1"
+//     }
+//   }
+// }
+`
+          : undefined
       )
     );
   }

packages/use-intl/test/react/useTranslations.test.tsx

@@ -663,21 +663,38 @@ describe('error handling', () => {
   it('warns for invalid namespace keys', () => {
     const onError = jest.fn();
 
-    render(
+    function Component() {
+      return (
+        <>
+          <p>{useTranslations('a.b')('c.d')}</p>
+          <p>{useTranslations('a.b')('e')}</p>
+          <p>{useTranslations('f')('g.h.j')}</p>
+          <p>{useTranslations('f.g')('h.j')}</p>
+          <p>{useTranslations('f.g.h')('j')}</p>
+          <p>{useTranslations()('f.g.h.j')}</p>
+        </>
+      );
+    }
+
+    const {container} = render(
       <IntlProvider
         locale="en"
         messages={{'a.b': {'c.d': 'ABCD', e: 'E'}, f: {g: {'h.j': 'FGHJ'}}}}
         onError={onError}
       >
-        <span />
+        <Component />
       </IntlProvider>
     );
 
     const error: IntlError = onError.mock.calls[0][0];
     expect(error.code).toBe(IntlErrorCode.INVALID_KEY);
-    expect(error.message).toBe(
+    expect(error.message.split('\n').slice(0, 3).join('\n')).toBe(
       'INVALID_KEY: Namespace keys can not contain the character "." as this is used to express nesting. Please remove it or replace it with another character.\n\nInvalid keys: a.b, c.d (at a.b), h.j (at f.g)'
     );
+
+    expect(container.innerHTML).toBe(
+      '<p>a.b.c.d</p><p>a.b.e</p><p>f.g.h.j</p><p>f.g.h.j</p><p>f.g.h.j</p><p>f.g.h.j</p>'
+    );
   });
 
   it('shows an error when trying to render an object with `t`', () => {