[i18n-audio] Use 'audioID' naming instead of 'audioKey' (#3989)

apps/mark-scan/backend/schema.sql

@@ -31,8 +31,8 @@ create table audio_clips (
   foreign key (language_code) references languages(code)
 );
 
-create table ui_string_audio_keys (
+create table ui_string_audio_ids (
   language_code text primary key,
-  data text not null, -- JSON blob - see libs/types/UiStringAudioKeysSchema
+  data text not null, -- JSON blob - see libs/types/UiStringAudioIdsSchema
   foreign key (language_code) references languages(code)
 );

apps/mark/backend/schema.sql

@@ -30,8 +30,8 @@ create table audio_clips (
   foreign key (language_code) references languages(code)
 );
 
-create table ui_string_audio_keys (
+create table ui_string_audio_ids (
   language_code text primary key,
-  data text not null, -- JSON blob - see libs/types/UiStringAudioKeysSchema
+  data text not null, -- JSON blob - see libs/types/UiStringAudioIdsSchema
   foreign key (language_code) references languages(code)
 );

apps/scan/backend/schema.sql

@@ -106,8 +106,8 @@ create table audio_clips (
   foreign key (language_code) references languages(code)
 );
 
-create table ui_string_audio_keys (
+create table ui_string_audio_ids (
   language_code text primary key,
-  data text not null, -- JSON blob - see libs/types/UiStringAudioKeysSchema
+  data text not null, -- JSON blob - see libs/types/UiStringAudioIdsSchema
   foreign key (language_code) references languages(code)
 );

libs/backend/src/ui_strings/ui_strings_api.ts

@@ -5,7 +5,7 @@ import { Logger } from '@votingworks/logging';
 import {
   Dictionary,
   LanguageCode,
-  UiStringAudioKeys,
+  UiStringAudioIds,
   UiStringTranslations,
   UiStringsApi,
 } from '@votingworks/types';
@@ -35,20 +35,20 @@ export function createUiStringsApi(context: UiStringsApiContext): UiStringsApi {
       );
     },
 
-    getUiStringAudioKeys(input: {
+    getUiStringAudioIds(input: {
       languageCode: LanguageCode;
-    }): Optional<UiStringAudioKeys> {
+    }): Optional<UiStringAudioIds> {
       throw new Error(
         `Not yet implemented. Requested language code: ${input.languageCode}`
       );
     },
 
     getAudioClipsBase64(input: {
       languageCode: LanguageCode;
-      audioKeys: string[];
+      audioIds: string[];
     }): Dictionary<string> {
       throw new Error(
-        `Not yet implemented. Requested language code: ${input.languageCode} | audioKeys: ${input.audioKeys}`
+        `Not yet implemented. Requested language code: ${input.languageCode} | audioIds: ${input.audioIds}`
       );
     },
   };

libs/backend/src/ui_strings/ui_strings_api_test_runner.ts

@@ -33,17 +33,17 @@ export function runUiStringApiTests(params: {
     ).toThrow(/not yet implemented/i);
   });
 
-  test('getUiStringAudioKeys throws not-yet-implemented error', () => {
+  test('getUiStringAudioIds throws not-yet-implemented error', () => {
     expect(() =>
-      api.getUiStringAudioKeys({ languageCode: LanguageCode.CHINESE })
+      api.getUiStringAudioIds({ languageCode: LanguageCode.CHINESE })
     ).toThrow(/not yet implemented/i);
   });
 
   test('getAudioClipsBase64 throws not-yet-implemented error', () => {
     expect(() =>
       api.getAudioClipsBase64({
         languageCode: LanguageCode.ENGLISH,
-        audioKeys: ['abc123', 'd1e2f3'],
+        audioIds: ['abc123', 'd1e2f3'],
       })
     ).toThrow(/not yet implemented/i);
   });

libs/types/src/ballot_package.ts

@@ -7,16 +7,16 @@ import {
 import { SystemSettings } from './system_settings';
 import { BallotPackageMetadata } from './ballot_package_metadata';
 import { UiStringAudioClips } from './ui_string_audio_clips';
-import { UiStringAudioKeysPackage } from './ui_string_audio_keys';
+import { UiStringAudioIdsPackage } from './ui_string_audio_ids';
 import { UiStringsPackage } from './ui_string_translations';
 
 export enum BallotPackageFileName {
   APP_STRINGS = 'appStrings.json',
   AUDIO_CLIPS = 'audioClips.jsonl',
-  AUDIO_KEYS = 'audioKeys.json',
   ELECTION = 'election.json',
   METADATA = 'metadata.json',
   SYSTEM_SETTINGS = 'systemSettings.json',
+  UI_STRING_AUDIO_IDS = 'uiStringAudioIds.json',
 }
 
 export interface BallotPackage {
@@ -25,7 +25,7 @@ export interface BallotPackage {
   // TODO(kevin) once all machines support system settings, make systemSettings required
   systemSettings?: SystemSettings;
   uiStringAudioClips?: UiStringAudioClips; // TODO(kofi): Make required
-  uiStringAudioKeys?: UiStringAudioKeysPackage; // TODO(kofi): Make required
+  uiStringAudioIds?: UiStringAudioIdsPackage; // TODO(kofi): Make required
   uiStrings?: UiStringsPackage; // TODO(kofi): Make required
 }
 

libs/types/src/index.ts

@@ -28,7 +28,7 @@ export * from './system_settings';
 export * as Tabulation from './tabulation';
 export * from './tallies';
 export * from './ui_string_audio_clips';
-export * from './ui_string_audio_keys';
+export * from './ui_string_audio_ids';
 export * from './ui_string_translations';
 export * from './ui_strings_api';
 export * from './ui_theme';

libs/types/src/ui_string_audio_clips.test.ts

@@ -5,27 +5,27 @@ import { UiStringAudioClipSchema } from './ui_string_audio_clips';
 test('valid structure', () => {
   const result = safeParseJson(
     JSON.stringify({
-      data: 'test data',
-      key: 'testKey',
-      lang: LanguageCode.CHINESE,
+      dataBase64: 'test data',
+      id: 'testKey',
+      languageCode: LanguageCode.CHINESE,
     }),
     UiStringAudioClipSchema
   );
 
   expect(result.isOk()).toEqual(true);
   expect(result.ok()).toEqual({
-    data: 'test data',
-    key: 'testKey',
-    lang: LanguageCode.CHINESE,
+    dataBase64: 'test data',
+    id: 'testKey',
+    languageCode: LanguageCode.CHINESE,
   });
 });
 
 test('invalid language code', () => {
   const result = safeParseJson(
     JSON.stringify({
-      data: 'test data',
-      key: 'testKey',
-      lang: 'Klingon',
+      dataBase64: 'test data',
+      id: 'testKey',
+      languageCode: 'Klingon',
     }),
     UiStringAudioClipSchema
   );
@@ -36,8 +36,8 @@ test('invalid language code', () => {
 test('missing field', () => {
   const result = safeParseJson(
     JSON.stringify({
-      data: 'test data',
-      lang: LanguageCode.SPANISH,
+      dataBase64: 'test data',
+      languageCode: LanguageCode.SPANISH,
     }),
     UiStringAudioClipSchema
   );

libs/types/src/ui_string_audio_clips.ts

@@ -6,18 +6,18 @@ import { LanguageCode } from './language_code';
  * A single audio clip record in the audio clips JSONL file in a ballot package.
  */
 export interface UiStringAudioClip {
-  data: string;
-  key: string;
-  lang: LanguageCode;
+  dataBase64: string;
+  id: string;
+  languageCode: LanguageCode;
 }
 
 /**
  * A single audio clip record in the audio clips JSONL file in a ballot package.
  */
 export const UiStringAudioClipSchema: z.ZodType<UiStringAudioClip> = z.object({
-  data: z.string(),
-  key: z.string(),
-  lang: z.nativeEnum(LanguageCode),
+  dataBase64: z.string(),
+  id: z.string(),
+  languageCode: z.nativeEnum(LanguageCode),
 });
 
 /**

libs/types/src/ui_string_audio_keys.test.ts → libs/types/src/ui_string_audio_ids.test.ts

@@ -1,12 +1,12 @@
 import { safeParseJson } from './generic';
 import { LanguageCode } from './language_code';
 import {
-  UiStringAudioKeysPackage,
-  UiStringAudioKeysPackageSchema,
-} from './ui_string_audio_keys';
+  UiStringAudioIdsPackage,
+  UiStringAudioIdsPackageSchema,
+} from './ui_string_audio_ids';
 
 test('valid structure', () => {
-  const testPackage: UiStringAudioKeysPackage = {
+  const testPackage: UiStringAudioIdsPackage = {
     [LanguageCode.SPANISH]: {
       appString: ['a1b2c3', 'f5e6d7'],
       appStringNested: {
@@ -21,7 +21,7 @@ test('valid structure', () => {
 
   const result = safeParseJson(
     JSON.stringify(testPackage),
-    UiStringAudioKeysPackageSchema
+    UiStringAudioIdsPackageSchema
   );
 
   expect(result.isOk()).toEqual(true);
@@ -38,7 +38,7 @@ test('invalid language code', () => {
         appString: ['4f4f4f', '3d3d3d'],
       },
     }),
-    UiStringAudioKeysPackageSchema
+    UiStringAudioIdsPackageSchema
   );
 
   expect(result.isOk()).toEqual(false);
@@ -52,7 +52,7 @@ test('invalid values', () => {
         invalid: '4f4f4f',
       },
     }),
-    UiStringAudioKeysPackageSchema
+    UiStringAudioIdsPackageSchema
   );
 
   expect(result.isOk()).toEqual(false);
@@ -70,7 +70,7 @@ test('invalid nesting', () => {
         },
       },
     }),
-    UiStringAudioKeysPackageSchema
+    UiStringAudioIdsPackageSchema
   );
 
   expect(result.isOk()).toEqual(false);

libs/types/src/ui_string_audio_ids.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+
+import { Dictionary } from './generic';
+import { LanguageCode } from './language_code';
+
+type AudioIdList = string[];
+
+/**
+ * Map of UI string key to a sequence of related speech audio clip IDs.
+ *
+ * Follows i18next JSON schema and supports one level of nesting.
+ * See: https://www.i18next.com/misc/json-format
+ */
+export type UiStringAudioIds = Dictionary<
+  AudioIdList | Dictionary<AudioIdList>
+>;
+
+const AudioIdListSchema: z.ZodType<AudioIdList> = z.array(z.string());
+
+/**
+ * Map of UI string key to a sequence of related speech audio clip IDs.
+ *
+ * Follows i18next JSON schema and supports one level of nesting.
+ * See: https://www.i18next.com/misc/json-format
+ */
+export const UiStringAudioIdsSchema: z.ZodType<UiStringAudioIds> = z.record(
+  z.union([AudioIdListSchema, z.record(AudioIdListSchema)])
+);
+
+/**
+ * Map of language code to {@link UiStringAudioIds}.
+ */
+export type UiStringAudioIdsPackage = Partial<
+  Record<LanguageCode, UiStringAudioIds>
+>;
+
+/**
+ * Map of language code to {@link UiStringAudioIds}.
+ */
+export const UiStringAudioIdsPackageSchema: z.ZodType<UiStringAudioIdsPackage> =
+  z.record(z.nativeEnum(LanguageCode), UiStringAudioIdsSchema);

libs/types/src/ui_strings_api.ts

@@ -2,7 +2,7 @@ import { Optional } from '@votingworks/basics';
 
 import { Dictionary } from './generic';
 import { LanguageCode } from './language_code';
-import { UiStringAudioKeys } from './ui_string_audio_keys';
+import { UiStringAudioIds } from './ui_string_audio_ids';
 import { UiStringTranslations } from './ui_string_translations';
 
 export interface UiStringsApi {
@@ -12,16 +12,16 @@ export interface UiStringsApi {
     languageCode: LanguageCode;
   }): Optional<UiStringTranslations>;
 
-  getUiStringAudioKeys(input: {
+  getUiStringAudioIds(input: {
     languageCode: LanguageCode;
-  }): Optional<UiStringAudioKeys>;
+  }): Optional<UiStringAudioIds>;
 
   /**
-   * Returns a map of the given audio keys to corresponding audio data in
+   * Returns a map of the given audio IDs to corresponding audio data in
    * Base64-encoded byte format.
    */
   getAudioClipsBase64(input: {
     languageCode: LanguageCode;
-    audioKeys: string[];
+    audioIds: string[];
   }): Dictionary<string>;
 }