# FormattedKintMessage

A wrapper component around `react-intl`'s `FormattedMessage` that enhances internationalization capabilities by providing automatic key resolution, direct value overrides, and flexible fallback messaging. **FormattedKintMessage** is designed to work within the `k-int` internationalization ecosystem, leveraging `useIntlKey` for intelligent message key lookup via `useIntlKey` and other intl hooks. [See intl hooks for details](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/-/tree/main/src/lib/hooks/intlHooks)

## Basic Usage

Below is an example demonstrating the most basic use of **FormattedKintMessage** to display translated text using automatic key resolution.

```jsx
import { FormattedKintMessage } from '@k-int/stripes-kint-components';

const MyInternationalizedComponent = () => (
  <div>
    {/* Resolves key using intlKey/intlNS from context or props */}
    <FormattedKintMessage id="title.greeting" intlKey="myModule" intlNS="myApp" />
  </div>
);

export default MyInternationalizedComponent;
```

### Explanation

* **`id`**: The relative ID for your message, which will be prefixed by the resolved `intlKey`.

* **`intlKey` / `intlNS`**: These props are used by `useIntlKey` to determine the base prefix for your message ID, allowing for flexible internationalization key management.

---

## Override and Fallback Message Usage

**`overrideValue`** and **`fallbackMessage`** both provide ways to control the message displayed, but they serve distinct purposes:

* **`overrideValue`**: Use this when you want to **explicitly define** the content to be displayed, entirely bypassing the translation lookup process for the `id` prop.
  * The `overrideValue` can be a direct string (e.g., "Custom Text") or another existing `react-intl` message key (e.g., "common.cancelButton").
  * If it's a key, `FormattedKintMessage` will attempt to format that key; otherwise, it displays the string literally.
  * This is useful for dynamic content that might not have a static translation key or for providing specific, hardcoded text for a particular instance.
  * As of `stripes-kint-components ^3.0.0`, `overrideValue` must be a string.

* **`fallbackMessage`**: Use this when you expect a translation to exist for your primary `id`, but you want a **graceful, silent fallback** if that translation is unexpectedly missing.
  * This prevents `react-intl`'s default console warnings for missing messages.
  * The `fallbackMessage` can also be a direct string or another existing `react-intl` message key.
  * It acts as a safety net, ensuring *something* is displayed even if the primary translation isn't available.

**In summary:**

* Choose `overrideValue` for **deliberate replacement** of the translation.

* Choose `fallbackMessage` for **graceful handling of missing translations**.

```jsx
import { FormattedKintMessage } from '@k-int/stripes-kint-components';

const OverrideAndFallbackExample = () => (
  <div>
    {/* Using an overrideValue (direct string) */}
    <FormattedKintMessage id="unimportant.key" overrideValue="This is a direct message." />

    {/* Using an overrideValue (another existing intl key) */}
    <FormattedKintMessage id="unused.key" overrideValue="someOtherIntlKey" />

    {/* Using a fallbackMessage when the primary key is not found (direct string) */}
    <FormattedKintMessage id="missing.message" fallbackMessage="Default message if not found." />

    {/* Using a fallbackMessage that is itself an existing intl key */}
    <FormattedKintMessage id="another.missing.message" fallbackMessage="common.error.generic" />
  </div>
);
```

## Props

| Prop | Type | Required | Description |
| :----------------------- | :--------------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fallbackMessage` | `string` | ✕ | A message or `react-intl` key to display if the primary `id` (after `intlKey` resolution) does not have a corresponding translation. This acts as a silent `defaultMessage` without console warnings. If it is a key, it will be formatted; otherwise, it will be displayed literally. |
| `id` | `string` | ✓ | The relative message ID to be translated. This ID is combined with the `intlKey` (resolved via `useIntlKey`) to form the full translation key. |
| `intlKey` | `string` | ✕ | A base internationalization key passed to the internal `useIntlKey` hook to resolve the full message path. |
| `intlNS` | `string` | ✕ | An internationalization namespace passed to the internal `useIntlKey` hook for resolving the full message path. |
| `overrideValue` | `string` | ✕ | A string value that, if present, takes precedence over all other translation logic. It can be a direct string to display or another `react-intl` message `id`. If it's a key, it will be formatted; otherwise, it will be displayed literally. **As of `stripes-kint-components ^3.0.0`, this must be a string.** |
| `...formattedMessageProps` | `object` | ✕ | Any additional props supported by `react-intl`'s original `FormattedMessage` component, such as `values` for injecting dynamic content into the message, `tagName`, etc. |