@posthog/core 1.27.9 → 1.28.1

package/src/surveys/translations.ts

@@ -0,0 +1,244 @@
+import { SurveyQuestionTranslation, SurveyTranslation } from '../types'
+import { createLogger, isArray, isUndefined } from '../utils'
+
+const logger = createLogger('[SurveyTranslations]')
+
+export type DetectSurveyLanguageOptions = {
+  overrideLanguage?: unknown
+  storedPersonProperties?: unknown
+  locale?: unknown
+}
+
+function getTrimmedLanguage(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null
+}
+
+export function getLanguageFromStoredPersonProperties(storedPersonProperties: unknown): string | null {
+  if (
+    !storedPersonProperties ||
+    typeof storedPersonProperties !== 'object' ||
+    !('language' in storedPersonProperties)
+  ) {
+    return null
+  }
+
+  return getTrimmedLanguage(storedPersonProperties.language)
+}
+
+export function detectSurveyLanguage({
+  overrideLanguage,
+  storedPersonProperties,
+  locale,
+}: DetectSurveyLanguageOptions): string | null {
+  const explicitLanguage = getTrimmedLanguage(overrideLanguage)
+  if (explicitLanguage) {
+    logger.info(`Using override display language: ${explicitLanguage}`)
+    return explicitLanguage
+  }
+
+  const personLanguage = getLanguageFromStoredPersonProperties(storedPersonProperties)
+  if (personLanguage) {
+    logger.info(`Using person property language: ${personLanguage}`)
+    return personLanguage
+  }
+
+  const detectedLocale = getTrimmedLanguage(locale)
+  if (detectedLocale) {
+    logger.info(`Using detected locale: ${detectedLocale}`)
+    return detectedLocale
+  }
+
+  logger.info('No user language detected')
+  return null
+}
+
+export function normalizeLanguageCode(languageCode: string): string {
+  return languageCode.toLowerCase()
+}
+
+export function getBaseLanguage(languageCode: string): string {
+  return languageCode.split('-')[0]
+}
+
+export function findBestTranslationMatch(
+  translations: Record<string, unknown> | undefined,
+  targetLanguage: string
+): string | null {
+  if (!translations || !targetLanguage) {
+    return null
+  }
+
+  const normalizedTarget = normalizeLanguageCode(targetLanguage)
+
+  const exactMatch = Object.keys(translations).find((key) => normalizeLanguageCode(key) === normalizedTarget)
+  if (exactMatch) {
+    logger.debug(`Found exact translation match: ${exactMatch}`)
+    return exactMatch
+  }
+
+  if (normalizedTarget.includes('-')) {
+    const baseLanguage = getBaseLanguage(normalizedTarget)
+    const baseMatch = Object.keys(translations).find((key) => normalizeLanguageCode(key) === baseLanguage)
+    if (baseMatch) {
+      logger.debug(`Found base language translation match: ${baseMatch} (from ${targetLanguage})`)
+      return baseMatch
+    }
+  }
+
+  return null
+}
+
+function isTranslatedChoices(
+  questionTranslation: SurveyQuestionTranslation
+): questionTranslation is SurveyQuestionTranslation & { choices: string[] } {
+  return isArray(questionTranslation.choices)
+}
+
+function hasThankYouTranslation(translation: SurveyTranslation): boolean {
+  return (
+    !isUndefined(translation.thankYouMessageHeader) ||
+    !isUndefined(translation.thankYouMessageDescription) ||
+    !isUndefined(translation.thankYouMessageCloseButtonText)
+  )
+}
+
+type TranslatableSurveyAppearance = {
+  thankYouMessageHeader?: string
+  thankYouMessageDescription?: string | null
+  thankYouMessageCloseButtonText?: string
+}
+
+type TranslatableSurveyQuestion = {
+  question: string
+  description?: string | null
+  buttonText?: string
+  link?: string | null
+  lowerBoundLabel?: string
+  upperBoundLabel?: string
+  choices?: string[]
+  translations?: Record<string, SurveyQuestionTranslation>
+}
+
+type TranslatableSurvey<TQuestion extends TranslatableSurveyQuestion = TranslatableSurveyQuestion> = {
+  name: string
+  translations?: Record<string, SurveyTranslation>
+  appearance?: TranslatableSurveyAppearance | null
+  questions: TQuestion[]
+}
+
+function mergeQuestionTranslation<TQuestion extends TranslatableSurveyQuestion>(
+  question: TQuestion,
+  targetLanguage: string
+): { question: TQuestion; matchedKey: string | null; hasChanges: boolean } {
+  const translationKey = findBestTranslationMatch(question.translations, targetLanguage)
+  if (!translationKey) {
+    return { question, matchedKey: null, hasChanges: false }
+  }
+
+  const questionTranslation = question.translations?.[translationKey]
+  if (!questionTranslation) {
+    return { question, matchedKey: null, hasChanges: false }
+  }
+
+  const translated: TQuestion = { ...question }
+  let hasChanges = false
+
+  if (!isUndefined(questionTranslation.question)) {
+    translated.question = questionTranslation.question
+    hasChanges = true
+  }
+  if (!isUndefined(questionTranslation.description)) {
+    translated.description = questionTranslation.description
+    hasChanges = true
+  }
+  if (!isUndefined(questionTranslation.buttonText)) {
+    translated.buttonText = questionTranslation.buttonText
+    hasChanges = true
+  }
+
+  if ('link' in translated && !isUndefined(questionTranslation.link)) {
+    translated.link = questionTranslation.link
+    hasChanges = true
+  }
+
+  if ('lowerBoundLabel' in translated && !isUndefined(questionTranslation.lowerBoundLabel)) {
+    translated.lowerBoundLabel = questionTranslation.lowerBoundLabel
+    hasChanges = true
+  }
+  if ('upperBoundLabel' in translated && !isUndefined(questionTranslation.upperBoundLabel)) {
+    translated.upperBoundLabel = questionTranslation.upperBoundLabel
+    hasChanges = true
+  }
+
+  if ('choices' in translated && isTranslatedChoices(questionTranslation)) {
+    translated.choices = questionTranslation.choices
+    hasChanges = true
+  }
+
+  return {
+    question: hasChanges ? translated : question,
+    matchedKey: hasChanges ? translationKey : null,
+    hasChanges,
+  }
+}
+
+export function applySurveyTranslation<
+  TQuestion extends TranslatableSurveyQuestion,
+  TSurvey extends TranslatableSurvey<TQuestion>,
+>(survey: TSurvey, targetLanguage: string): { survey: TSurvey; matchedKey: string | null } {
+  const translationKey = findBestTranslationMatch(survey.translations, targetLanguage)
+
+  const translated: TSurvey = { ...survey }
+  let hasTranslation = false
+
+  if (translationKey) {
+    const translation = survey.translations?.[translationKey]
+    if (translation) {
+      logger.info(`Applying survey-level translation for language: ${translationKey}`)
+
+      if (!isUndefined(translation.name)) {
+        translated.name = translation.name
+        hasTranslation = true
+      }
+
+      if (translated.appearance) {
+        translated.appearance = { ...translated.appearance }
+
+        if (!isUndefined(translation.thankYouMessageHeader)) {
+          translated.appearance.thankYouMessageHeader = translation.thankYouMessageHeader
+          hasTranslation = true
+        }
+        if (!isUndefined(translation.thankYouMessageDescription)) {
+          translated.appearance.thankYouMessageDescription = translation.thankYouMessageDescription
+          hasTranslation = true
+        }
+        if (!isUndefined(translation.thankYouMessageCloseButtonText)) {
+          translated.appearance.thankYouMessageCloseButtonText = translation.thankYouMessageCloseButtonText
+          hasTranslation = true
+        }
+      } else if (hasThankYouTranslation(translation)) {
+        hasTranslation = true
+      }
+    }
+  }
+
+  const translatedResults = survey.questions.map((question) => mergeQuestionTranslation(question, targetLanguage))
+  const translatedQuestions = translatedResults.map((result) => result.question)
+  const anyQuestionTranslated = translatedResults.some((result) => result.hasChanges)
+
+  let questionMatchedKey: string | null = null
+  if (!translationKey) {
+    questionMatchedKey = translatedResults.find((result) => result.matchedKey)?.matchedKey || null
+  }
+
+  if (anyQuestionTranslated) {
+    translated.questions = translatedQuestions
+    hasTranslation = true
+    logger.info(`Applied question-level translations for language: ${targetLanguage}`)
+  }
+
+  return {
+    survey: translated,
+    matchedKey: hasTranslation ? translationKey || questionMatchedKey : null,
+  }
+}

package/src/testing/test-utils.ts

@@ -36,6 +36,7 @@ export const delay = (ms: number): Promise<void> => {
 
 export const createMockLogger = (): Logger => {
   return {
+    debug: jest.fn((...args) => console.debug(...args)),
     info: jest.fn((...args) => console.log(...args)),
     warn: jest.fn((...args) => console.warn(...args)),
     error: jest.fn((...args) => console.error(...args)),

package/src/types.ts

@@ -344,6 +344,18 @@ export type PostHogRemoteConfig = {
     | {
         [key: string]: JsonType
       }
+
+  /**
+   * Logs feature remote config. When a map, `captureConsoleLogs` (boolean)
+   * is the local opt-in flag for `console.*` autocapture (read by the JS
+   * SDK's `PostHogLogs` extension to decide whether to load the autocapture
+   * bundle).
+   */
+  logs?:
+    | boolean
+    | {
+        [key: string]: JsonType
+      }
 }
 
 export type FeatureFlagValue = string | boolean
@@ -606,16 +618,34 @@ export interface SurveyValidationRule {
   errorMessage?: string
 }
 
+export interface SurveyTranslation {
+  name?: string
+  thankYouMessageHeader?: string
+  thankYouMessageDescription?: string
+  thankYouMessageCloseButtonText?: string
+}
+
+export interface SurveyQuestionTranslation {
+  question?: string
+  description?: string | null
+  buttonText?: string
+  link?: string | null
+  lowerBoundLabel?: string
+  upperBoundLabel?: string
+  choices?: string[]
+}
+
 type SurveyQuestionBase = {
   question: string
   id: string
-  description?: string
+  description?: string | null
   descriptionContentType?: SurveyQuestionDescriptionContentType
   optional?: boolean
   buttonText?: string
   originalQuestionIndex: number
   branching?: NextQuestionBranching | EndBranching | ResponseBasedBranching | SpecificQuestionBranching
   validation?: SurveyValidationRule[]
+  translations?: Record<string, SurveyQuestionTranslation>
 }
 
 export type BasicSurveyQuestion = SurveyQuestionBase & {
@@ -624,7 +654,7 @@ export type BasicSurveyQuestion = SurveyQuestionBase & {
 
 export type LinkSurveyQuestion = SurveyQuestionBase & {
   type: SurveyQuestionType.Link
-  link?: string
+  link?: string | null
 }
 
 export type RatingSurveyQuestion = SurveyQuestionBase & {
@@ -686,6 +716,10 @@ export type SurveyResponse = {
   surveys: Survey[]
 }
 
+export type SurveyResponseValue = string | number | string[] | null
+
+export type SurveyResponses = Record<string, SurveyResponseValue>
+
 export type SurveyCallback = (surveys: Survey[]) => void
 
 export enum SurveyMatchType {
@@ -728,6 +762,7 @@ export type Survey = {
   name: string
   description?: string
   type: SurveyType
+  translations?: Record<string, SurveyTranslation>
   feature_flag_keys?: {
     key: string
     value?: string
@@ -790,6 +825,7 @@ export type ActionStepType = {
 }
 
 export type Logger = {
+  debug: (...args: any[]) => void
   info: (...args: any[]) => void
   warn: (...args: any[]) => void
   error: (...args: any[]) => void

package/src/utils/logger.ts

@@ -2,10 +2,10 @@ import { Logger } from '../types'
 
 // We want to make sure to get the original console methods as soon as possible
 type ConsoleLike = {
+  debug: (...args: any[]) => void
   log: (...args: any[]) => void
   warn: (...args: any[]) => void
   error: (...args: any[]) => void
-  debug: (...args: any[]) => void
 }
 
 function createConsole(consoleLike: ConsoleLike = console): ConsoleLike {
@@ -23,7 +23,7 @@ export const _createLogger = (
   maybeCall: (fn: () => void) => void,
   consoleLike: ConsoleLike
 ): Logger => {
-  function _log(level: 'log' | 'warn' | 'error', ...args: any[]) {
+  function _log(level: 'debug' | 'log' | 'warn' | 'error', ...args: any[]) {
     maybeCall(() => {
       const consoleMethod = consoleLike[level]
       consoleMethod(prefix, ...args)
@@ -31,6 +31,10 @@ export const _createLogger = (
   }
 
   const logger: Logger = {
+    debug: (...args: any[]) => {
+      _log('debug', ...args)
+    },
+
     info: (...args: any[]) => {
       _log('log', ...args)
     },