@c15t/svelte 3.0.0-alpha.0

package/dist/use-banner-visibility.svelte.js

@@ -0,0 +1,108 @@
+import { onMount, tick, untrack } from 'svelte';
+const DEFAULT_DURATION_MS = 200;
+const readDurationMs = function readDurationMs(target) {
+    if (typeof document === 'undefined') {
+        return DEFAULT_DURATION_MS;
+    }
+    const value = getComputedStyle(target ?? document.documentElement)
+        .getPropertyValue('--consent-banner-animation-duration')
+        .trim();
+    if (!value) {
+        return DEFAULT_DURATION_MS;
+    }
+    if (value.endsWith('ms')) {
+        return Number.parseFloat(value) || DEFAULT_DURATION_MS;
+    }
+    if (value.endsWith('s')) {
+        return Number.parseFloat(value) * 1000 || DEFAULT_DURATION_MS;
+    }
+    return Number.parseFloat(value) || DEFAULT_DURATION_MS;
+};
+/**
+ * Visibility / mount lifecycle for the consent banner.
+ *
+ * - On show: mounts the element with `.bannerHidden`, awaits Svelte commit,
+ *   forces a reflow so the browser observes that initial style, then flips
+ *   to `.bannerVisible`. The CSS transition fires automatically — no JS
+ *   timing coordination.
+ * - On hide: flips to `.bannerHidden`, then unmounts after the duration
+ *   declared by the `--consent-banner-animation-duration` CSS variable.
+ * - When animation is disabled (provider option or `prefers-reduced-motion`):
+ *   toggles synchronously, skipping the show reflow and the hide timer.
+ * - Server render: when the very first evaluation already says "show" — which
+ *   only happens once a `prefetch` has seeded a resolved policy, since
+ *   without one the kernel's model is `null` and `activeUI` is `'none'` — the
+ *   banner starts mounted and *visible*. That puts the shell in the first
+ *   HTML and skips the entry animation on hydration, which would otherwise
+ *   replay an animation the user has already seen painted. Client-triggered
+ *   shows still take the animated path.
+ */
+export const useBannerVisibility = function useBannerVisibility(getShouldShow, getDisableAnimation) {
+    // Read outside a reactive scope: this is the one-shot server/initial
+    // decision, not an ongoing dependency. The $effect below owns the rest.
+    const serverVisible = untrack(getShouldShow);
+    let isVisible = $state(serverVisible);
+    let isMounted = $state(serverVisible);
+    let shouldRender = $state(serverVisible);
+    onMount(() => {
+        isMounted = true;
+    });
+    let bannerEl = $state();
+    $effect(() => {
+        const shouldShow = getShouldShow();
+        const disableAnim = getDisableAnimation();
+        if (shouldShow) {
+            shouldRender = true;
+            if (disableAnim) {
+                isVisible = true;
+                return;
+            }
+            let cancelled = false;
+            void (async () => {
+                await tick();
+                if (cancelled) {
+                    return;
+                }
+                // Force layout so the browser observes `bannerHidden` before we
+                // flip to `bannerVisible`. Without this, a fresh mount can
+                // compute the final style first and skip the entry transition.
+                void bannerEl?.offsetHeight;
+                isVisible = true;
+            })();
+            return () => {
+                cancelled = true;
+            };
+        }
+        if (!isVisible) {
+            shouldRender = false;
+            return;
+        }
+        if (disableAnim) {
+            isVisible = false;
+            shouldRender = false;
+            return;
+        }
+        isVisible = false;
+        const timer = setTimeout(() => {
+            shouldRender = false;
+        }, readDurationMs(bannerEl ?? null));
+        return () => clearTimeout(timer);
+    });
+    return {
+        get bannerEl() {
+            return bannerEl;
+        },
+        set bannerEl(el) {
+            bannerEl = el;
+        },
+        get isMounted() {
+            return isMounted;
+        },
+        get isVisible() {
+            return isVisible;
+        },
+        get shouldRender() {
+            return shouldRender;
+        },
+    };
+};

package/dist/utils.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Theme and styling utilities for Svelte components.
+ */
+import type { AllThemeKeys, ClassNameStyle, Theme, ThemeCSSVariables } from '@c15t/ui/theme';
+/**
+ * Default design tokens for the theme system.
+ */
+export declare const defaultTheme: Required<Omit<Theme, "slots">>;
+/**
+ * Maps theme tokens to CSS variables.
+ */
+export declare const themeToVars: (theme: Theme, isDark?: boolean) => ThemeCSSVariables;
+/**
+ * Generates a CSS string for the theme variables.
+ */
+export declare const generateThemeCSS: (theme: Theme) => string;
+/**
+ * Resolves styles for a component, merging theme slot styles with component styles.
+ */
+export declare const resolveComponentStyles: (themeKey: AllThemeKeys, theme: Theme | undefined, componentStyle: ClassNameStyle | undefined, noStyle: boolean | undefined) => ClassNameStyle;
+/** Resolve only host appearance; policy action constraints remain in core. */
+export declare const resolveConsentActionStyle: (theme: Theme | undefined, action: "accept" | "reject" | "customize" | "dismiss" | "save") => {
+    variant?: "primary" | "neutral";
+    mode?: "filled" | "stroke" | "lighter" | "ghost";
+};

package/dist/utils.js

@@ -0,0 +1,32 @@
+/**
+ * Theme and styling utilities for Svelte components.
+ */
+import { defaultTheme as baseDefaultTheme, generateThemeCSS as baseGenerateThemeCSS, themeToVars as baseThemeToVars, } from '@c15t/ui/theme';
+import { resolveStyles as baseResolveStyles } from '@c15t/ui/utils';
+/**
+ * Default design tokens for the theme system.
+ */
+export const defaultTheme = baseDefaultTheme;
+/**
+ * Maps theme tokens to CSS variables.
+ */
+export const themeToVars = function themeToVars(theme, isDark = false) {
+    return baseThemeToVars(theme, isDark);
+};
+/**
+ * Generates a CSS string for the theme variables.
+ */
+export const generateThemeCSS = function generateThemeCSS(theme) {
+    return baseGenerateThemeCSS(theme);
+};
+/**
+ * Resolves styles for a component, merging theme slot styles with component styles.
+ */
+export const resolveComponentStyles = function resolveComponentStyles(themeKey, theme, componentStyle, noStyle) {
+    return baseResolveStyles(themeKey, theme, componentStyle, noStyle);
+};
+/** Resolve only host appearance; policy action constraints remain in core. */
+export const resolveConsentActionStyle = (theme, action) => {
+    const specific = action === 'save' ? undefined : theme?.consentActions?.[action];
+    return { ...theme?.consentActions?.default, ...specific };
+};

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const version = "3.0.0-alpha.0";

package/dist/version.js

@@ -0,0 +1,2 @@
+// Generated by genversion.
+export const version = '3.0.0-alpha.0';

package/docs/README.md

@@ -0,0 +1,88 @@
+# @c15t/svelte
+
+> Svelte and SvelteKit v3 providers, request loading and static hosting with Inth.
+
+These docs ship inside the package so coding agents can read them offline. Open the topic file you need from the list below — paths are relative to this file.
+
+## Using these docs
+
+These docs describe v3. Start with Inth hosted setup, identify the framework, router and deployment, then read its quickstart. Static sites can use Inth directly. Use page Markdown and package-bundled docs for targeted context. Verify scripts, rejection, reload and preferences; banner visibility alone is insufficient.
+
+## Start here
+
+- [Svelte quickstart](./frameworks/svelte/quickstart.md)
+- [SvelteKit quickstart](./frameworks/sveltekit/quickstart.md)
+- [Customize your consent interface](./customization/overview.md): Choose presentation, theme tokens, slots or custom markup for the change you need.
+- [Verify consent before shipping](./guides/verify-consent.md): Test requests, policy resolution, persistence, navigation and preference changes in a production build.
+- [Upgrade to v3 policies](./upgrade-v3.md): Migrate policy configuration, consent records, callbacks, and custom transports to the v3 policy system.
+
+## More documentation
+
+[Documentation index](https://c15t.com/docs/llms.txt) · [Full Markdown context](https://c15t.com/llms-full.txt). Prefer the index and individual pages for focused tasks.
+
+## Frameworks
+
+- [Quickstart](./frameworks/svelte/quickstart.md): Mount c15t components and a persistent preferences link in a Svelte 5 application.
+- [Quickstart](./frameworks/sveltekit/quickstart.md): Resolve consent in a SvelteKit server load and hydrate the provider, or initialize in the browser on static hosting.
+
+## Guides
+
+- [Understand consent state](./guides/consent-state.md): Distinguish policy resolution, effective permissions, explicit choices, notices and privacy signals.
+- [Data fetching and transports](./guides/data-fetching.md): Choose cached manifests, backend init or offline policy resolution, and understand where consent records are saved.
+- [Choose a deployment mode](./guides/deployment-modes.md): Choose who runs your consent backend, then select manifest, init or offline resolution for your deployment.
+- [Troubleshoot consent](./guides/troubleshooting.md): Diagnose missing banners, early vendor requests, lost choices and hydration differences.
+- [Verify consent before shipping](./guides/verify-consent.md): Test requests, policy resolution, persistence, navigation and preference changes in a production build.
+
+## Customization
+
+- [Customize your consent interface](./customization/overview.md): Choose presentation, theme tokens, slots or custom markup for the change you need.
+- [Banner styling recipes](./customization/recipes.md): See real v3 components and reuse the exact theme configuration behind the examples.
+- [Style component slots](./customization/slots.md): Target a specific c15t component part without replacing its markup or behavior.
+- [Theme tokens and CSS](./customization/tokens.md): Style c15t with semantic tokens and use the stylesheet that matches your CSS tooling.
+- [Copy and translations](./customization/translations.md): Change consent wording through i18n and test the complete prompt and preferences flow.
+
+## Integrations
+
+- [Adobe Analytics](./integrations/adobe-analytics.md): Configure Adobe Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Ahrefs Analytics](./integrations/ahrefs-analytics.md): Configure Ahrefs Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Amplitude](./integrations/amplitude.md): Configure Amplitude with c15t v3, understand measurement permission and verify loading and revocation.
+- [Custom integrations](./integrations/building-integrations.md): Define loading, initialization and consent-change behavior for a vendor without a helper.
+- [Clearbit](./integrations/clearbit.md): Configure Clearbit with c15t v3, understand marketing permission and verify loading and revocation.
+- [Cloudflare Web Analytics](./integrations/cloudflare-web-analytics.md): Configure Cloudflare Web Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Crisp](./integrations/crisp.md): Configure Crisp with c15t v3, understand functionality permission and verify loading and revocation.
+- [Databuddy](./integrations/databuddy.md): Configure Databuddy's initial and updated consent state with c15t v3.
+- [Fathom Analytics](./integrations/fathom-analytics.md): Configure Fathom Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Google Maps](./integrations/google-maps.md): Prevent a map iframe from mounting before the required permission.
+- [Google Tag](./integrations/google-tag.md): Configure gtag with c15t Consent Mode signals and understand its loading behavior.
+- [Google Tag Manager](./integrations/google-tag-manager.md): Load GTM with c15t consent signals and verify the tags inside your container.
+- [Heap](./integrations/heap.md): Configure Heap with c15t v3, understand measurement permission and verify loading and revocation.
+- [Hightouch](./integrations/hightouch.md): Configure Hightouch with c15t v3, understand measurement permission and verify loading and revocation.
+- [Hotjar](./integrations/hotjar.md): Configure Hotjar with c15t v3, understand measurement permission and verify loading and revocation.
+- [Intercom](./integrations/intercom.md): Load the Intercom messenger with functionality permission and configure its region.
+- [LinkedIn Insight Tag](./integrations/linkedin-insights.md): Configure LinkedIn Insight Tag with c15t v3, understand marketing permission and verify loading and revocation.
+- [LogRocket](./integrations/logrocket.md): Configure LogRocket with c15t v3, understand measurement permission and verify loading and revocation.
+- [Matomo Analytics](./integrations/matomo-analytics.md): Choose gated loading or Matomo consent signaling and configure the correct tracker endpoints.
+- [Meta Pixel](./integrations/meta-pixel.md): Register the Meta Pixel under marketing permission and verify event calls after revocation.
+- [Microsoft Clarity](./integrations/microsoft-clarity.md): Configure Microsoft Clarity with c15t v3, understand measurement permission and verify loading and revocation.
+- [Microsoft UET](./integrations/microsoft-uet.md): Configure Microsoft UET with c15t v3, understand marketing permission and verify loading and revocation.
+- [Mixpanel](./integrations/mixpanel-analytics.md): Configure Mixpanel with c15t v3, understand measurement permission and verify loading and revocation.
+- [OpenAI Pixel](./integrations/openai-pixel.md): Configure the OpenAI Measurement Pixel for ChatGPT Ads with c15t v3, manage marketing permission and verify conversion delivery.
+- [Overview](./integrations/overview.md): Find all c15t integrations for analytics, tag managers, advertising, chat and embedded content.
+- [Pirsch](./integrations/pirsch.md): Configure Pirsch with c15t v3, understand measurement permission and verify loading and revocation.
+- [Plausible Analytics](./integrations/plausible-analytics.md): Configure Plausible Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [PostHog](./integrations/posthog.md): Choose PostHog loading and cookieless behavior, configure the region, and synchronize v3 permissions.
+- [Promptwatch](./integrations/promptwatch.md): Configure Promptwatch with c15t v3, understand measurement permission and verify loading and revocation.
+- [Reddit Pixel](./integrations/reddit-pixel.md): Configure Reddit Pixel with c15t v3, understand marketing permission and verify loading and revocation.
+- [RudderStack](./integrations/rudderstack.md): Gate the RudderStack browser SDK or map c15t categories to destination consent IDs.
+- [Rybbit Analytics](./integrations/rybbit-analytics.md): Configure Rybbit Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Segment](./integrations/segment.md): Configure Segment with c15t v3, understand measurement permission and verify loading and revocation.
+- [Snapchat Pixel](./integrations/snapchat-pixel.md): Configure Snapchat Pixel with c15t v3, understand marketing permission and verify loading and revocation.
+- [TikTok Pixel](./integrations/tiktok-pixel.md): Configure TikTok Pixel with c15t v3, understand marketing permission and verify loading and revocation.
+- [Umami Analytics](./integrations/umami-analytics.md): Configure Umami Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Vercel Analytics](./integrations/vercel-analytics.md): Configure Vercel Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [X Pixel](./integrations/x-pixel.md): Configure X Pixel with c15t v3, understand marketing permission and verify loading and revocation.
+- [YouTube](./integrations/youtube.md): Gate YouTube embeds with c15t v3 in Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit or JavaScript.
+
+## Reference
+
+- [Upgrade to v3 policies](./upgrade-v3.md): Migrate policy configuration, consent records, callbacks, and custom transports to the v3 policy system.

package/docs/customization/overview.md

@@ -0,0 +1,45 @@
+---
+title: Customize your consent interface
+description: Choose presentation, theme tokens, slots or custom markup for the
+  change you need.
+group: customization
+---
+
+## Start with the change you want
+
+| Change                                    | Use                                 | Why                                                          |
+| ----------------------------------------- | ----------------------------------- | ------------------------------------------------------------ |
+| Banner shape or location                  | Presentation or banner props        | Keeps policy actions and built-in layout behavior            |
+| Brand colors, radius, typography, spacing | Theme tokens                        | Changes related component parts together                     |
+| One card, footer, title or button group   | Component slots                     | Targets existing markup                                      |
+| Labels, descriptions or language          | i18n configuration                  | Keeps banner and preferences copy consistent                 |
+| A different component structure           | Compound components where available | Retains the component behavior while changing markup         |
+| Your own interaction and markup           | Headless APIs                       | You own rendering, focus behavior and policy action coverage |
+
+Most brand changes need tokens and a few slots. Start there before opting out
+of the stock styles. The [recipes](./recipes.md) show how each
+choice affects a real banner.
+
+## Keep behavior and appearance separate
+
+Presentation controls the prompt's shape, position and blocking behavior.
+Policy controls which actions and rights are required. Changing colors or button
+order does not change a saved choice or policy scope.
+
+A choice wall always blocks. Notices never block and cannot become a wall merely
+because `variant: 'wall'` was requested. Preference dialogs remain centered;
+prompt positioning does not move them. Required actions omitted from a custom
+layout can be restored by the policy renderer.
+
+## Use the adapter's configuration shape
+
+React and Next.js accept provider `theme`, `presentation` and `components`
+options. Vue and Nuxt expose their own shared configuration, including CSS
+`tokens` and component slots. Svelte accepts its provider options and theme
+contract. Astro serializes integration options and uses the selected adapter for
+dialogs. Do not move a configuration object between frameworks without checking
+the target types.
+
+Read [tokens and CSS](./tokens.md),
+[slots](./slots.md) or
+[copy and translations](./translations.md) for the next step.

package/docs/customization/recipes.md

@@ -0,0 +1,79 @@
+---
+title: Banner styling recipes
+description: See real v3 components and reuse the exact theme configuration
+  behind the examples.
+group: customization
+---
+
+## A branded floating card
+
+This theme uses a green primary action and a four-pixel large radius. Accept and
+Reject keep matching treatment. The component's required action behavior stays
+intact.
+
+![A v3 floating consent card with green Customize action, matching Accept and Reject buttons, and compact corners](../assets/v3/brand-card.png)
+
+```ts
+import { defineTheme } from '@c15t/ui/theme';
+
+export const brandTheme = defineTheme({
+	colors: { primary: '#2f6f4e' },
+	consentActions: {
+		primary: { mode: 'filled', variant: 'primary' },
+	},
+	radius: { lg: '4px' },
+});
+
+```
+
+Install `@c15t/ui` to use `defineTheme` directly. Pass `brandTheme` as `theme` in
+your existing React or Next.js provider options. Keep your Inth mode and script
+configuration. The theme source above is also imported by the runnable example,
+so the rendered result and the documentation use the same values.
+
+## Change the shape without rebuilding the banner
+
+```tsx
+<ConsentBanner variant="bar" />
+```
+
+![The same green theme on a full-width v3 consent bar with the actions arranged across its footer](../assets/v3/brand-bar.png)
+
+A bar changes the prompt's footprint. It does not change policy, grant categories
+or require a headless implementation.
+
+```tsx
+<ConsentBanner variant="wall" />
+```
+
+![A centered v3 choice wall with a backdrop, using the same green action theme](../assets/v3/choice-wall.png)
+
+A choice wall blocks interaction with the page. A notice never blocks; requesting
+a wall for a notice falls back to a non-blocking presentation.
+
+## Carry the theme into preferences
+
+![The v3 preferences dialog with optional category toggles and a green Save Settings action](../assets/v3/preferences.png)
+
+Keep a preferences link after the banner closes. Test a reject action, reopen
+the dialog, change one category and save. A branded prompt is only part of the
+consent flow.
+
+## Check narrow screens
+
+![The branded v3 floating card at a 375-pixel viewport, with Accept and Reject sharing a row and Customize below](../assets/v3/mobile-card.png)
+
+This example fits a 375-pixel viewport without horizontal overflow. Test your
+own longest translations and font settings before adopting the same sizing.
+
+## Run the examples
+
+The source repository contains resettable Storybook examples under
+`Docs / Customization`: Brand Card, Brand Bar and Choice Wall. Each demo uses
+in-memory consent and no analytics; Reset example returns it to a fresh choice.
+The screenshots above come from these v3 examples.
+
+The stories are suitable for isolated iframe previews on a version-matched
+Storybook deployment. Keep source code and the explanation on this page when
+embedding them, so the recipe remains usable in Markdown and offline package
+docs. A live preview must use the same v3 revision as the documentation.

package/docs/customization/slots.md

@@ -0,0 +1,55 @@
+---
+title: Style component slots
+description: Target a specific c15t component part without replacing its markup or behavior.
+group: customization
+---
+
+## Use slots for local changes
+
+In React and Next.js, put per-part attributes in `options.components`. This
+fragment belongs in an existing provider's options:
+
+```tsx
+components: {
+  banner: {
+    card: { className: 'rounded-none shadow-none' },
+    title: { className: 'font-semibold' },
+    footer: { className: 'border-t' },
+  },
+}
+```
+
+The class names above assume Tailwind. A slot can also receive `style` and other
+supported element attributes. Keep shared colors and radius scales in tokens;
+use slots when only one component part should change.
+
+## Read attributes on the right element
+
+The banner root carries `data-prompt`, `data-model`, `data-variant`,
+`data-position` and `data-blocking`. Its child card does not inherit those HTML
+attributes. In Tailwind, give the root `className: 'group'` and use
+`group-data-[variant=bar]:...` on a child slot.
+
+| React banner slot                  | Use                                   |
+| ---------------------------------- | ------------------------------------- |
+| `root`                             | Position wrapper and state attributes |
+| `cardShell`                        | Card sizing and branding container    |
+| `card`                             | Visible card                          |
+| `header`, `title`, `description`   | Heading and explanatory copy          |
+| `footer`, `actions`, `actionGroup` | Action layout                         |
+| `rights`, `rightLink`              | Preferences access controls           |
+| `overlay`                          | Backdrop for blocking presentation    |
+
+Buttons expose `data-action` for action-specific CSS. Test notices as well as
+choice prompts; a notice uses acknowledgement rather than accept/reject.
+
+## When to remove styles
+
+`noStyle` removes the built-in component styling. It does not supply replacement
+layout, spacing, focus indicators or responsive behavior. Use it when you intend
+to own all of that work, not as the first response to a token that appears to do
+nothing.
+
+If the markup itself must change, use the adapter's compound components or
+headless API. The slot objects above are the React contract; check Vue and Svelte
+slot types before reusing them.

package/docs/customization/tokens.md

@@ -0,0 +1,76 @@
+---
+title: Theme tokens and CSS
+description: Style c15t with semantic tokens and use the stylesheet that matches
+  your CSS tooling.
+group: customization
+---
+
+## Load the stock stylesheet once
+
+React, Next.js and Svelte provide `styles.css`. Import the adapter's stylesheet
+at the app's global entry point. Vue includes styles in its components; Astro
+adds styles through its integration.
+
+```tsx
+import 'c15t/react/styles.css';
+```
+
+The standard stylesheet places rules in `@layer components`. For Tailwind 3,
+use the `styles.tw3.css` entry instead of the standard stylesheet, between the
+components and utilities directives in your Tailwind entry:
+
+```css
+@tailwind base;
+@tailwind components;
+@import 'c15t/react/styles.tw3.css';
+@tailwind utilities;
+```
+
+Do not load both c15t stylesheet variants. For Tailwind 4 or unlayered CSS,
+inspect layer order before reaching for `!important`.
+
+## Set semantic values together
+
+This React theme changes the brand color and large corner radius. Include
+hover and foreground colors when overriding raw variables so the button remains
+readable in each state.
+
+```ts
+import { defineTheme } from '@c15t/ui/theme';
+
+export const theme = defineTheme({
+  colors: { primary: '#2f6f4e' },
+  radius: { lg: '4px' },
+  consentActions: {
+    primary: { variant: 'primary', mode: 'filled' },
+    dismiss: { variant: 'neutral', mode: 'stroke' },
+  },
+});
+```
+
+Install `@c15t/ui` if importing its theme helper directly. Pass `theme` in your
+provider options. `consentActions` selects styling by action role. A per-action
+entry overrides `primary`, which overrides `default`.
+
+## Target a prompt with CSS
+
+```css
+[data-prompt][data-model='opt-in'] {
+  --c15t-primary: #2f6f4e;
+  --c15t-primary-hover: #24563c;
+  --c15t-text-on-primary: #fff;
+}
+```
+
+Use attributes exposed by the rendered component, not guessed class names.
+Test the prompt and the preferences dialog separately because tokens scoped to
+one prompt do not automatically reach a portaled dialog.
+
+| Size variable                       | Default | Target        |
+| ----------------------------------- | ------- | ------------- |
+| `--consent-banner-max-width`        | `440px` | Floating card |
+| `--consent-banner-widget-max-width` | `20rem` | Widget        |
+| `--consent-banner-wall-max-width`   | `30rem` | Choice wall   |
+
+Test long translations and small screens after changing width or typography.
+A compact banner must still fit the required actions.

package/docs/customization/translations.md

@@ -0,0 +1,49 @@
+---
+title: Copy and translations
+description: Change consent wording through i18n and test the complete prompt
+  and preferences flow.
+group: customization
+---
+
+## Configure shared messages
+
+Use provider `i18n` for wording that should stay consistent across components.
+For React, this fragment belongs in `ConsentProvider` options:
+
+```tsx
+i18n: {
+  messages: {
+    en: {
+      common: {
+        acceptAll: 'Accept all',
+        rejectAll: 'Reject optional',
+        customize: 'Choose cookies',
+        acknowledge: 'Got it',
+      },
+    },
+  },
+}
+```
+
+Supply the same message keys in each supported locale. A one-off component prop
+such as `dismissButtonText` is useful for one banner; use translations for a
+site-wide change. Astro's serializable integration options and Vue's module
+configuration have their own types, so verify those shapes before copying a
+React object.
+
+## Write labels that describe the action
+
+Accept and Reject record a choice. Customize opens preferences. Acknowledge
+dismisses a notice and does not record a grant. Do not label a notice dismissal
+"Accept all" or make a preferences link sound like it submits an opt-out.
+
+The notice acknowledgement uses `common.acknowledge`, with `common.dismiss` as
+a fallback for older translation bundles. Keep the displayed label and the
+command's effect aligned.
+
+## Test more than English
+
+Try the longest labels you support at a narrow width, with browser zoom and
+right-to-left text where relevant. Check banner actions, category descriptions,
+legal links and the preferences save action. Translate explanations as well as
+buttons so a visitor can make an informed choice.