Rename translation properties for clarity (#10061)

src/lib/translation/index.tsx

@@ -103,7 +103,6 @@ async function attemptTranslation(
 export function useTranslate({
   key,
   forceGoogleTranslate = false,
-  postLangCodes,
 }: TranslationOptions) {
   const context = useContext(Context)
   if (!context) {
@@ -121,14 +120,17 @@ export function useTranslate({
 
   const translate = useCallback(
     async (params: TranslationFunctionParams) => {
-      return context.translate({
-        ...params,
-        key,
-        forceGoogleTranslate,
-        postLangCodes,
-      })
+      return context.translate(
+        {
+          ...params,
+        },
+        {
+          key,
+          forceGoogleTranslate,
+        },
+      )
     },
-    [context, forceGoogleTranslate, key, postLangCodes],
+    [context, forceGoogleTranslate, key],
   )
 
   const clearTranslation = useCallback(
@@ -208,17 +210,34 @@ export function Provider({children}: React.PropsWithChildren<unknown>) {
   }, [])
 
   const translate = useCallback<ContextType['translate']>(
-    async ({
-      key,
-      text,
-      targetLangCode,
-      sourceLangCode,
-      sourceSelection = 'automatic',
-      postLangCodes,
-      ...options
-    }) => {
-      if (options?.forceGoogleTranslate || !HAS_ON_DEVICE_TRANSLATION) {
-        await googleTranslate(text, targetLangCode, sourceLangCode)
+    async (
+      {
+        text,
+        expectedTargetLanguage,
+        expectedSourceLanguage,
+        possibleSourceLanguages,
+        forceGoogleTranslate: forceGoogleTranslateOverride,
+      },
+      {key, forceGoogleTranslate},
+    ) => {
+      const shouldForceGoogleTranslate = Boolean(
+        forceGoogleTranslateOverride ?? forceGoogleTranslate,
+      )
+
+      ax.metric('translate', {
+        os: Platform.OS,
+        possibleSourceLanguages,
+        expectedTargetLanguage: expectedTargetLanguage,
+        textLength: text.length,
+        googleTranslate: shouldForceGoogleTranslate,
+      })
+
+      if (shouldForceGoogleTranslate || !HAS_ON_DEVICE_TRANSLATION) {
+        await googleTranslate(
+          text,
+          expectedTargetLanguage,
+          expectedSourceLanguage,
+        )
         return
       }
 
@@ -232,16 +251,18 @@ export function Provider({children}: React.PropsWithChildren<unknown>) {
       try {
         const result = await attemptTranslation(
           text,
-          targetLangCode,
-          sourceLangCode,
+          expectedTargetLanguage,
+          expectedSourceLanguage,
         )
         ax.metric('translate:result', {
-          method: 'on-device',
+          success: true,
           os: Platform.OS,
-          sourceSelection,
-          sourceLanguage: result.sourceLanguage,
-          targetLanguage: result.targetLanguage,
-          postLanguages: postLangCodes,
+          possibleSourceLanguages,
+          expectedSourceLanguage: expectedSourceLanguage ?? null,
+          expectedTargetLanguage,
+          resultSourceLanguage: result.sourceLanguage,
+          resultTargetLanguage: result.targetLanguage,
+          textLength: text.length,
         })
         if (!IS_ANDROID) {
           LayoutAnimation.configureNext(LayoutAnimation.Presets.easeInEaseOut)
@@ -253,7 +274,7 @@ export function Provider({children}: React.PropsWithChildren<unknown>) {
             translatedText: result.translatedText,
             sourceLanguage: result.sourceLanguage,
             targetLanguage: result.targetLanguage,
-            postLanguages: postLangCodes,
+            postLanguages: possibleSourceLanguages,
           },
         }))
       } catch (e) {
@@ -261,12 +282,14 @@ export function Provider({children}: React.PropsWithChildren<unknown>) {
         // On-device translation failed (language pack missing or user
         // dismissed the download prompt).
         ax.metric('translate:result', {
-          method: 'fallback-alert',
+          success: false,
           os: Platform.OS,
-          sourceSelection,
-          sourceLanguage: sourceLangCode ?? null,
-          targetLanguage: targetLangCode,
-          postLanguages: postLangCodes,
+          possibleSourceLanguages,
+          expectedSourceLanguage: expectedSourceLanguage ?? null,
+          expectedTargetLanguage,
+          resultSourceLanguage: null,
+          resultTargetLanguage: null,
+          textLength: text.length,
         })
         let errorMessage = l`Device failed to translate :(`
         if (!IS_ANDROID) {

src/lib/translation/index.web.tsx

@@ -22,7 +22,7 @@ const clearTranslation = (_key: string) => {}
 /**
  * Web always opens Google Translate.
  */
-export function useTranslate({key, postLangCodes}: TranslationOptions) {
+export function useTranslate({key}: TranslationOptions) {
   const context = useContext(Context)
   if (!context) {
     throw new Error(
@@ -33,14 +33,17 @@ export function useTranslate({key, postLangCodes}: TranslationOptions) {
   // Always call hooks in consistent order
   const translate = useCallback(
     async (params: TranslationFunctionParams) => {
-      return context.translate({
-        ...params,
-        key,
-        forceGoogleTranslate: true,
-        postLangCodes,
-      })
+      return context.translate(
+        {
+          ...params,
+        },
+        {
+          key,
+          forceGoogleTranslate: true,
+        },
+      )
     },
-    [key, context, postLangCodes],
+    [key, context],
   )
 
   const clearTranslation = useCallback(() => {
@@ -61,8 +64,24 @@ export function Provider({children}: React.PropsWithChildren<unknown>) {
   const googleTranslate = useGoogleTranslate()
 
   const translate = useCallback<ContextType['translate']>(
-    async ({text, targetLangCode, sourceLangCode}) => {
-      await googleTranslate(text, targetLangCode, sourceLangCode)
+    async ({
+      text,
+      expectedTargetLanguage,
+      expectedSourceLanguage,
+      possibleSourceLanguages,
+    }) => {
+      ax.metric('translate', {
+        os: 'web',
+        possibleSourceLanguages,
+        expectedTargetLanguage,
+        textLength: text.length,
+        googleTranslate: true,
+      })
+      await googleTranslate(
+        text,
+        expectedTargetLanguage,
+        expectedSourceLanguage,
+      )
     },
     [ax, googleTranslate],
   )

src/lib/translation/types.ts

@@ -22,38 +22,45 @@ export type TranslationFunctionParams = {
   /**
    * The language to translate the text into.
    */
-  targetLangCode: string
+  expectedTargetLanguage: string
   /**
-   * The source language of the text. Will auto-detect if not provided.
+   * We auto-detect the source language by default, but the user has the option
+   * to specify a source language if they want to. If this value is present, it
+   * means the user selected a source language, or we were certain of the
+   * source language and want to specify it explicitly.
    */
-  sourceLangCode?: string
+  expectedSourceLanguage?: string
   /**
-   * Whether we auto-detected the language or it was selected manually. Defaults to 'automatic'.
+   * The languages the content might be in, such as the user-supplied
+   * language codes on posts. Currently only available on posts.
    */
-  sourceSelection?: 'automatic' | 'manual'
+  possibleSourceLanguages?: string[]
+  /**
+   * Override the default behavior and always use Google Translate.
+   */
+  forceGoogleTranslate?: boolean
 }
 
 export type TranslationOptions = {
-  key: string
-  forceGoogleTranslate?: boolean
   /**
-   * The language(s) of the post being translated. Used for analytics purposes
-   * to understand translation usage patterns better. Optional because it may
-   * not always be available (e.g. if the post text is empty or if the
-   * translation is triggered from a non-post
-   * context).
+   * A unique key to identify this translation instance e.g. the post URI
    */
-  postLangCodes?: string[]
+  key: string
+  /**
+   * Override the default behavior and always use Google Translate.
+   */
+  forceGoogleTranslate?: boolean
 }
 
 export type TranslationFunction = (
-  parameters: TranslationFunctionParams,
+  params: TranslationFunctionParams,
 ) => Promise<void>
 
 export type ContextType = {
   translationState: Record<string, TranslationState>
   translate: (
-    parameters: TranslationFunctionParams & TranslationOptions,
+    params: TranslationFunctionParams,
+    options: TranslationOptions,
   ) => Promise<void>
   clearTranslation: (key: string) => void
   acquireTranslation: (key: string) => () => void