@c15t/scripts 2.2.0 → 3.0.0-alpha.0

package/docs/README.md

@@ -1,62 +1,88 @@
 # @c15t/scripts
 
-> Consent-aware script integration docs for analytics, advertising pixels, tag managers, widgets, and custom loaders.
+> Consent-aware vendor integrations and Consent Mode loading contracts.
 
 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
+
+- [Connect your integrations](./integrations/overview.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
 
-Install and configure c15t in JavaScript, React, and Next.js applications.
+- [JavaScript script loading](./frameworks/javascript/script-loader.md): Attach a script loader to the consent kernel and dispose it with the application.
+- [Load scripts with consent](./frameworks/next/script-loader.md): Register vendor scripts in your existing Next.js ConsentRoot and handle loading and revocation.
+- [Load scripts with consent](./frameworks/react/script-loader.md): Register vendor scripts once and let effective permissions control loading.
+
+## 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.
 
-- [Script Loader](./frameworks/javascript/script-loader.md): Gate third-party scripts behind consent — load Google Analytics, Meta Pixel, and other tracking scripts only when users grant permission.
-- [Script Loader](./frameworks/next/script-loader.md): Gate third-party scripts behind consent in Next.js — load Google Analytics, Meta Pixel, and other tracking scripts only when users grant permission.
-- [Script Loader](./frameworks/react/script-loader.md): Gate third-party scripts behind consent in React — load Google Analytics, Meta Pixel, and other tracking scripts only when users grant permission.
+## 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
 
-Connect analytics, advertising, maps, media, and other third-party tools behind consent.
-
-- [Adobe Analytics](./integrations/adobe-analytics.md): Adobe Analytics loaded through an Adobe Experience Platform Data Collection Tags embed URL.
-- [Ahrefs Analytics](./integrations/ahrefs-analytics.md): Cookieless web analytics from Ahrefs with a prebuilt helper that wires the project key into a c15t-managed script.
-- [Amplitude](./integrations/amplitude.md): Load Amplitude Browser SDK 2 with c15t and gate product analytics behind measurement consent.
-- [Build a Custom Script Integration](./integrations/building-integrations.md): Learn when to use a raw Script, when to build a reusable manifest-backed integration, and how to debug and test custom consent-aware scripts in c15t.
-- [Clearbit](./integrations/clearbit.md): Visitor and company enrichment loaded with Clearbit's account-keyed tags.js snippet.
-- [Cloudflare Web Analytics](./integrations/cloudflare-web-analytics.md): Cookieless analytics from Cloudflare with a prebuilt helper that serializes the beacon config into the `data-cf-beacon` attribute.
-- [Crisp](./integrations/crisp.md): Load Crisp live chat with website ID, runtime, cookie, and session options.
-- [Databuddy](./integrations/databuddy.md): Databuddy is a privacy-focused analytics platform that helps you understand user behavior and track events. It supports cookieless tracking and manages consent automatically through c15t's consent state synchronization.
-- [Fathom Analytics](./integrations/fathom-analytics.md): Privacy-friendly cookieless analytics with a prebuilt helper that maps Fathom's data attributes into a c15t-managed script.
-- [Google Maps](./integrations/google-maps.md): Render Google Maps only after consent with one shared Maps JavaScript API loader and independently managed map instances.
-- [GA4 + Google Ads (gtag.js)](./integrations/google-tag.md): Send data to Google Analytics 4 and Google Ads with automatic Consent Mode v2 support.
-- [Google Tag Manager](./integrations/google-tag-manager.md): Deploy and manage marketing tags centrally with automatic consent state synchronization.
-- [Heap](./integrations/heap.md): Load Heap with c15t and gate autocapture product analytics behind measurement consent.
-- [Hightouch](./integrations/hightouch.md): Load Hightouch Events with c15t and gate the browser SDK behind measurement consent.
-- [Hotjar](./integrations/hotjar.md): Product analytics and behavior insights with a prebuilt helper that seeds Hotjar globals before loading the vendor bundle.
-- [Intercom](./integrations/intercom.md): Bootstrap Intercom settings and load the messenger widget bundle.
-- [LinkedIn Insights](./integrations/linkedin-insights.md): Track conversions and build matched audiences for LinkedIn advertising campaigns.
-- [LogRocket](./integrations/logrocket.md): Session replay and monitoring loaded after measurement consent with LogRocket's browser SDK.
-- [Matomo Analytics](./integrations/matomo-analytics.md): Load Matomo with c15t and keep Matomo's queue aligned with measurement consent.
-- [Meta Pixel](./integrations/meta-pixel.md): Track conversions and build audiences for Facebook and Instagram advertising campaigns.
-- [Microsoft Clarity](./integrations/microsoft-clarity.md): Session replay and behavior analytics with a prebuilt helper that keeps Clarity consent synchronized with c15t measurement state.
-- [Microsoft UET](./integrations/microsoft-uet.md): Track conversions and measure performance for Microsoft Advertising and Bing Ads.
-- [Mixpanel Analytics](./integrations/mixpanel-analytics.md): Load Mixpanel with c15t and let Mixpanel's own opt-in and opt-out APIs follow measurement consent.
-- [Integrations](./integrations/overview.md): Load analytics, pixels, tag managers, and widgets through c15t so consent state controls when they run, update, and appear in your consent UI.
-- [Pirsch](./integrations/pirsch.md): Privacy-friendly, cookieless analytics loaded with Pirsch's fixed script id and identification-code attributes.
-- [Plausible Analytics](./integrations/plausible-analytics.md): Privacy-friendly cookieless analytics with a prebuilt helper that preserves Plausible's queue bootstrap and loader attributes.
-- [PostHog](./integrations/posthog.md): PostHog is an open-source product analytics platform for tracking user behavior, session replays, feature flags, and A/B testing. It supports cookieless tracking, allowing analytics to continue even without cookie consent.
-- [Promptwatch](./integrations/promptwatch.md): Promptwatch analyzes traffic on your site for Artificial Intelligence (AI) traffic and usage insights. Data is stored in the EU without user-identifiable information.
-- [Reddit Pixel](./integrations/reddit-pixel.md): Track conversions and build retargeting audiences for Reddit advertising campaigns.
-- [RudderStack](./integrations/rudderstack.md): Load RudderStack's JavaScript SDK with c15t and gate the browser SDK behind measurement consent.
-- [Rybbit Analytics](./integrations/rybbit-analytics.md): Privacy-friendly analytics with script-tag configuration via Rybbit's data attributes.
-- [Segment](./integrations/segment.md): Load Segment Analytics.js with c15t and gate it behind measurement consent.
-- [Snapchat Pixel](./integrations/snapchat-pixel.md): Measure Snapchat ad performance and build remarketing audiences with a prebuilt pixel helper.
-- [TikTok Pixel](./integrations/tiktok-pixel.md): Measure ad performance and build audiences for TikTok advertising campaigns.
-- [Umami Analytics](./integrations/umami-analytics.md): Open-source, cookieless analytics with a prebuilt helper that maps Umami's data attributes into a c15t-managed script.
-- [Vercel Analytics](./integrations/vercel-analytics.md): Bootstrap Vercel Analytics with a declarative queue and script attributes.
-- [X Pixel (Twitter Pixel)](./integrations/x-pixel.md): Track conversions and build audiences for advertising campaigns on X (formerly Twitter).
-- [YouTube](./integrations/youtube.md): Keep YouTube iframes unmounted until consent with a privacy-enhanced, lazy-loaded React or Next.js embed.
+- [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
 
-Concepts, legal templates, open-source policies, and contributor documentation.
-
-- [Script Loader](./shared/react/guides/script-loader.md): Reference page for script loader.
+- [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.