# useTranslations must be used within IntlProvider

## TL;DR

Fixes the runtime error when useTranslations is called outside an IntlProvider. Wrap the component tree in IntlProvider or move the hook below the provider. Use when a new component crashes with this exact error. Not for messages that render in the wrong language.

## The error

```text
Error: [React Intl] useTranslations must be used within IntlProvider
```

## Fix it

### Step 1: Find the component calling the hook

```bash
grep -rn "useTranslations" src/components/BrokenPanel.* | head -5
```

Expected: You see the hook call in the crashing component.

### Step 2: Check the provider placement in the tree

```bash
grep -rn "IntlProvider" src/App.* src/index.* | head -5
```

Expected: You see where IntlProvider sits relative to the component.

### Step 3: Move the hook below the provider or wrap the subtree

```bash
node -e "console.log('wrap the panel in IntlProvider or hoist the provider above it')"
```

Expected: The component renders with translations available.

## When to use this

- A component crashes with the IntlProvider error
- The hook works in one page but not in a newly added one

## When NOT to use this

- Translations render but in the wrong language, that is a locale detection issue
- The provider exists but messages are empty, check the message loader

## Tool and version compatibility

- react-intl 5 and 6
- Also applies to next-intl's useTranslations in client components

## Variant phrasings

### error in a modal or portal

Portals render outside the provider subtree. Wrap the portal content explicitly.

### error in tests only

Tests that render components in isolation need a provider wrapper in the test setup.

## Why it happens

useTranslations reads the intl context created by IntlProvider. If the component is rendered outside that provider, there is no context to read, so the hook throws instead of returning undefined strings.

## Edge cases

- Lazy-loaded routes may mount before the provider initializes
- Multiple providers with different locales can shadow each other unexpectedly
- Storybook stories each need their own provider decorator

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_1EuPACsUJThEnRnTQzKESA