doc(gtm): i18n usage

docs/content/scripts/analytics/google-analytics.md

@@ -152,6 +152,188 @@ export const GoogleAnalyticsOptions = object({
 })
 ```
 
+## Multi-Domain and i18n Setup
+
+When working with multi-language applications or different domains, you may need to dynamically configure Google Analytics based on the current locale or domain.
+
+### Using with @nuxtjs/i18n
+
+For applications using [@nuxtjs/i18n](https://i18n.nuxtjs.org/), you can configure different Analytics IDs per locale:
+
+::code-group
+
+```vue [pages/index.vue - Plugin Approach]
+<script setup lang="ts">
+// Create a plugin to handle GA setup based on locale
+// plugins/google-analytics.client.ts
+export default defineNuxtPlugin(() => {
+  const { locale } = useI18n()
+
+  const analyticsIds = {
+    'en': 'GA_ID_ENGLISH',
+    'es': 'GA_ID_SPANISH',
+    'fr': 'GA_ID_FRENCH'
+  }
+
+  useScriptGoogleAnalytics({
+    id: analyticsIds[locale.value] || analyticsIds['en']
+  })
+})
+</script>
+```
+
+```vue [composables/useAnalytics.ts - Composable Approach]
+<script setup lang="ts">
+// Create a reusable composable
+export const useAnalytics = () => {
+  const { locale } = useI18n()
+
+  const analyticsIds = {
+    'en': 'GA_ID_ENGLISH',
+    'es': 'GA_ID_SPANISH',
+    'fr': 'GA_ID_FRENCH'
+  }
+
+  return useScriptGoogleAnalytics({
+    id: analyticsIds[locale.value] || analyticsIds['en']
+  })
+}
+
+// Usage in components
+const { proxy } = useAnalytics()
+proxy.gtag('event', 'page_view')
+</script>
+```
+
+```ts [nuxt.config.ts - Runtime Config Approach]
+export default defineNuxtConfig({
+  // Runtime configuration for different locales
+  runtimeConfig: {
+    public: {
+      scripts: {
+        googleAnalytics: {
+          ids: {
+            en: process.env.GA_ID_EN,
+            es: process.env.GA_ID_ES,
+            fr: process.env.GA_ID_FR
+          }
+        }
+      }
+    }
+  }
+})
+
+// Then in your component:
+// const config = useRuntimeConfig()
+// const { locale } = useI18n()
+// const gaId = config.public.scripts.googleAnalytics.ids[locale.value]
+// useScriptGoogleAnalytics({ id: gaId })
+```
+
+::
+
+### Custom Domain Detection
+
+For applications with different domains for different markets:
+
+```vue [app.vue]
+<script setup lang="ts">
+const getDomainBasedAnalyticsId = () => {
+  if (process.client) {
+    const hostname = window.location.hostname
+
+    const domainToId = {
+      'example.com': 'GA_ID_US',
+      'example.co.uk': 'GA_ID_UK',
+      'example.fr': 'GA_ID_FR',
+      'example.de': 'GA_ID_DE'
+    }
+
+    return domainToId[hostname] || 'GA_ID_DEFAULT'
+  }
+
+  // Server-side fallback - you might use headers or other logic
+  return 'GA_ID_DEFAULT'
+}
+
+const { proxy } = useScriptGoogleAnalytics({
+  id: getDomainBasedAnalyticsId()
+})
+</script>
+```
+
+### Advanced: Dynamic Configuration with Multiple Properties
+
+For complex setups where you need to send data to multiple Analytics properties:
+
+```vue [composables/useMultiAnalytics.ts]
+<script setup lang="ts">
+export const useMultiAnalytics = () => {
+  const { locale } = useI18n()
+
+  // Primary analytics for the current locale
+  const primary = useScriptGoogleAnalytics({
+    id: getAnalyticsId(locale.value),
+    key: 'primary-analytics'
+  })
+
+  // Global analytics for cross-locale analysis
+  const global = useScriptGoogleAnalytics({
+    id: 'GA_ID_GLOBAL',
+    key: 'global-analytics'
+  })
+
+  const trackEvent = (eventName: string, parameters: any = {}) => {
+    // Send to both analytics properties
+    primary.proxy.gtag('event', eventName, parameters)
+    global.proxy.gtag('event', eventName, {
+      ...parameters,
+      custom_locale: locale.value
+    })
+  }
+
+  return {
+    primary,
+    global,
+    trackEvent
+  }
+}
+
+function getAnalyticsId(locale: string): string {
+  const ids = {
+    'en': 'GA_ID_ENGLISH',
+    'es': 'GA_ID_SPANISH',
+    'fr': 'GA_ID_FRENCH'
+  }
+  return ids[locale] || ids['en']
+}
+</script>
+```
+
+### Best Practices
+
+1. **Performance Considerations**: Only load one Analytics script per page to avoid performance issues
+2. **Data Segmentation**: Use custom dimensions to segment data by locale/region instead of separate properties when possible
+3. **Cookie Domain**: Ensure your cookie domain settings in GA match your multi-domain setup
+4. **Cross-Domain Tracking**: Configure cross-domain tracking if users navigate between different domains
+
+```vue [Example: Locale-specific events]
+<script setup lang="ts">
+const { proxy } = useAnalytics()
+const { locale } = useI18n()
+
+// Send locale-aware events
+const trackPurchase = (value: number, currency: string) => {
+  proxy.gtag('event', 'purchase', {
+    value,
+    currency,
+    custom_locale: locale.value,
+    custom_market: getMarketFromLocale(locale.value)
+  })
+}
+</script>
+```
+
 ## Example
 
 Using Google Analytics only in production while using `gtag` to send a conversion event.

docs/content/scripts/tracking/google-tag-manager.md

@@ -154,6 +154,9 @@ export const GoogleTagManagerOptions = object({
 
     /** Referrer policy for analytics requests */
     authReferrerPolicy: optional(string()),
+
+    /** The URL of the script; useful for server-side GTM */
+    source: optional(string()),
   })
 ```
 
@@ -163,7 +166,37 @@ export const GoogleTagManagerOptions = object({
 type GoogleTagManagerInput = typeof GoogleTagManagerOptions & { onBeforeGtmStart?: (gtag: Gtag) => void }
 ```
 
-## Example
+## Examples
+
+### Server-Side GTM Setup
+
+Using a custom GTM script source for server-side implementations:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  scripts: {
+    registry: {
+      googleTagManager: {
+        id: 'GTM-XXXXXX',
+        source: 'https://your-domain.com/gtm.js'
+      }
+    }
+  }
+})
+```
+
+```vue
+<!-- Component usage -->
+<script setup lang="ts">
+const { proxy } = useScriptGoogleTagManager({
+  id: 'GTM-XXXXXX',
+  source: 'https://your-domain.com/gtm.js'
+})
+</script>
+```
+
+### Basic Usage
 
 Using Google Tag Manager only in production while using `dataLayer` to send a conversion event.