@platformos/platformos-common 0.0.8 → 0.0.9

package/src/path-utils.spec.ts

@@ -0,0 +1,350 @@
+import { describe, it, expect } from 'vitest';
+import {
+  PlatformOSFileType,
+  getFileType,
+  getAppPaths,
+  getModulePaths,
+  isKnownLiquidFile,
+  isPartial,
+  isPage,
+  isLayout,
+  isAuthorization,
+  isEmail,
+  isApiCall,
+  isSms,
+  isMigration,
+} from './path-utils';
+
+// Helper: build a realistic absolute URI
+const uri = (path: string) => `file:///project/${path}`;
+
+describe('getFileType', () => {
+  describe('app-level paths', () => {
+    it('identifies pages', () => {
+      expect(getFileType(uri('app/views/pages/home.liquid'))).toBe(PlatformOSFileType.Page);
+      expect(getFileType(uri('app/views/pages/nested/category/item.liquid'))).toBe(
+        PlatformOSFileType.Page,
+      );
+    });
+
+    it('identifies layouts', () => {
+      expect(getFileType(uri('app/views/layouts/default.liquid'))).toBe(PlatformOSFileType.Layout);
+    });
+
+    it('identifies partials in views/partials', () => {
+      expect(getFileType(uri('app/views/partials/header.liquid'))).toBe(PlatformOSFileType.Partial);
+      expect(getFileType(uri('app/views/partials/nested/card.liquid'))).toBe(
+        PlatformOSFileType.Partial,
+      );
+    });
+
+    it('identifies partials in app/lib', () => {
+      expect(getFileType(uri('app/lib/helpers/format.liquid'))).toBe(PlatformOSFileType.Partial);
+      expect(getFileType(uri('app/lib/utils.liquid'))).toBe(PlatformOSFileType.Partial);
+    });
+
+    it('identifies authorization_policies', () => {
+      expect(getFileType(uri('app/authorization_policies/can_edit.liquid'))).toBe(
+        PlatformOSFileType.Authorization,
+      );
+    });
+
+    it('identifies emails', () => {
+      expect(getFileType(uri('app/emails/welcome.liquid'))).toBe(PlatformOSFileType.Email);
+    });
+
+    it('identifies api_calls', () => {
+      expect(getFileType(uri('app/api_calls/create_user.liquid'))).toBe(PlatformOSFileType.ApiCall);
+    });
+
+    it('identifies smses', () => {
+      expect(getFileType(uri('app/smses/notification.liquid'))).toBe(PlatformOSFileType.Sms);
+    });
+
+    it('identifies migrations', () => {
+      expect(getFileType(uri('app/migrations/20230101_add_users.liquid'))).toBe(
+        PlatformOSFileType.Migration,
+      );
+    });
+
+    it('identifies graphql', () => {
+      expect(getFileType(uri('app/graphql/users.graphql'))).toBe(PlatformOSFileType.GraphQL);
+    });
+
+    it('identifies assets', () => {
+      expect(getFileType(uri('app/assets/app.js'))).toBe(PlatformOSFileType.Asset);
+      expect(getFileType(uri('app/assets/styles.css'))).toBe(PlatformOSFileType.Asset);
+    });
+  });
+
+  describe('module paths (modules/{name}/public|private/...)', () => {
+    it('identifies module pages', () => {
+      expect(getFileType(uri('modules/core/public/views/pages/home.liquid'))).toBe(
+        PlatformOSFileType.Page,
+      );
+      expect(getFileType(uri('modules/core/private/views/pages/admin.liquid'))).toBe(
+        PlatformOSFileType.Page,
+      );
+    });
+
+    it('identifies module layouts', () => {
+      expect(getFileType(uri('modules/core/public/views/layouts/default.liquid'))).toBe(
+        PlatformOSFileType.Layout,
+      );
+    });
+
+    it('identifies module partials in views/partials', () => {
+      expect(getFileType(uri('modules/core/public/views/partials/card.liquid'))).toBe(
+        PlatformOSFileType.Partial,
+      );
+    });
+
+    it('identifies module partials in lib', () => {
+      expect(getFileType(uri('modules/core/public/lib/utils.liquid'))).toBe(
+        PlatformOSFileType.Partial,
+      );
+      expect(getFileType(uri('modules/core/private/lib/internal.liquid'))).toBe(
+        PlatformOSFileType.Partial,
+      );
+    });
+
+    it('identifies module smses', () => {
+      expect(getFileType(uri('modules/core/public/smses/alert.liquid'))).toBe(
+        PlatformOSFileType.Sms,
+      );
+    });
+
+    it('identifies module graphql', () => {
+      expect(getFileType(uri('modules/core/public/graphql/query.graphql'))).toBe(
+        PlatformOSFileType.GraphQL,
+      );
+    });
+  });
+
+  describe('app/modules paths', () => {
+    it('identifies nested module partials in lib', () => {
+      expect(getFileType(uri('app/modules/core/public/lib/format.liquid'))).toBe(
+        PlatformOSFileType.Partial,
+      );
+    });
+
+    it('identifies nested module layouts', () => {
+      expect(getFileType(uri('app/modules/core/public/views/layouts/default.liquid'))).toBe(
+        PlatformOSFileType.Layout,
+      );
+    });
+  });
+
+  describe('false positive prevention — nested paths must not bleed into wrong type', () => {
+    it('app/lib/smses/file.liquid is Partial, not Sms', () => {
+      expect(getFileType(uri('app/lib/smses/file.liquid'))).toBe(PlatformOSFileType.Partial);
+    });
+
+    it('app/lib/emails/file.liquid is Partial, not Email', () => {
+      expect(getFileType(uri('app/lib/emails/file.liquid'))).toBe(PlatformOSFileType.Partial);
+    });
+
+    it('app/lib/api_calls/file.liquid is Partial, not ApiCall', () => {
+      expect(getFileType(uri('app/lib/api_calls/file.liquid'))).toBe(PlatformOSFileType.Partial);
+    });
+
+    it('modules/core/public/lib/smses/file.liquid is Partial, not Sms', () => {
+      expect(getFileType(uri('modules/core/public/lib/smses/file.liquid'))).toBe(
+        PlatformOSFileType.Partial,
+      );
+    });
+
+    it('modules/core/public/lib/emails/file.liquid is Partial, not Email', () => {
+      expect(getFileType(uri('modules/core/public/lib/emails/file.liquid'))).toBe(
+        PlatformOSFileType.Partial,
+      );
+    });
+  });
+
+  describe('unknown paths return undefined', () => {
+    it('returns undefined for a generator template with /lib/ in path', () => {
+      expect(
+        getFileType(uri('modules/core/generators/command/templates/lib/commands/create.liquid')),
+      ).toBeUndefined();
+    });
+
+    it('returns undefined for app/stupid/file.liquid', () => {
+      expect(getFileType(uri('app/stupid/file.liquid'))).toBeUndefined();
+    });
+
+    it('returns undefined for a file at project root', () => {
+      expect(getFileType(uri('file.liquid'))).toBeUndefined();
+    });
+
+    it('returns undefined for a path that only partially matches', () => {
+      // has 'views' but not 'views/pages' or 'views/layouts' etc.
+      expect(getFileType(uri('app/views/file.liquid'))).toBeUndefined();
+    });
+  });
+});
+
+describe('isKnownLiquidFile', () => {
+  it('returns true for all liquid file types', () => {
+    expect(isKnownLiquidFile(uri('app/views/pages/home.liquid'))).toBe(true);
+    expect(isKnownLiquidFile(uri('app/views/layouts/default.liquid'))).toBe(true);
+    expect(isKnownLiquidFile(uri('app/views/partials/header.liquid'))).toBe(true);
+    expect(isKnownLiquidFile(uri('app/lib/utils.liquid'))).toBe(true);
+    expect(isKnownLiquidFile(uri('app/authorization_policies/can_edit.liquid'))).toBe(true);
+    expect(isKnownLiquidFile(uri('app/emails/welcome.liquid'))).toBe(true);
+    expect(isKnownLiquidFile(uri('app/api_calls/create.liquid'))).toBe(true);
+    expect(isKnownLiquidFile(uri('app/smses/notify.liquid'))).toBe(true);
+    expect(isKnownLiquidFile(uri('app/migrations/001_init.liquid'))).toBe(true);
+  });
+
+  it('returns false for GraphQL files', () => {
+    expect(isKnownLiquidFile(uri('app/graphql/query.graphql'))).toBe(false);
+  });
+
+  it('returns false for asset files', () => {
+    expect(isKnownLiquidFile(uri('app/assets/app.js'))).toBe(false);
+  });
+
+  it('returns false for generator templates', () => {
+    expect(
+      isKnownLiquidFile(
+        uri('modules/core/generators/command/templates/lib/commands/create.liquid'),
+      ),
+    ).toBe(false);
+  });
+
+  it('returns false for unrecognized paths', () => {
+    expect(isKnownLiquidFile(uri('app/stupid/file.liquid'))).toBe(false);
+  });
+});
+
+describe('getAppPaths', () => {
+  it('returns correct paths for Page', () => {
+    expect(getAppPaths(PlatformOSFileType.Page)).toEqual(['app/views/pages']);
+  });
+
+  it('returns correct paths for Layout', () => {
+    expect(getAppPaths(PlatformOSFileType.Layout)).toEqual(['app/views/layouts']);
+  });
+
+  it('returns correct paths for Partial (two dirs)', () => {
+    expect(getAppPaths(PlatformOSFileType.Partial)).toEqual(['app/views/partials', 'app/lib']);
+  });
+
+  it('returns correct paths for GraphQL', () => {
+    expect(getAppPaths(PlatformOSFileType.GraphQL)).toEqual(['app/graphql']);
+  });
+
+  it('returns correct paths for Asset', () => {
+    expect(getAppPaths(PlatformOSFileType.Asset)).toEqual(['app/assets']);
+  });
+});
+
+describe('getModulePaths', () => {
+  it('returns all 8 module paths for Partial', () => {
+    expect(getModulePaths(PlatformOSFileType.Partial, 'mymodule')).toEqual([
+      'app/modules/mymodule/public/views/partials',
+      'app/modules/mymodule/private/views/partials',
+      'modules/mymodule/public/views/partials',
+      'modules/mymodule/private/views/partials',
+      'app/modules/mymodule/public/lib',
+      'app/modules/mymodule/private/lib',
+      'modules/mymodule/public/lib',
+      'modules/mymodule/private/lib',
+    ]);
+  });
+
+  it('returns all 4 module paths for GraphQL', () => {
+    expect(getModulePaths(PlatformOSFileType.GraphQL, 'mymodule')).toEqual([
+      'app/modules/mymodule/public/graphql',
+      'app/modules/mymodule/private/graphql',
+      'modules/mymodule/public/graphql',
+      'modules/mymodule/private/graphql',
+    ]);
+  });
+
+  it('returns all 4 module paths for Page', () => {
+    expect(getModulePaths(PlatformOSFileType.Page, 'core')).toEqual([
+      'app/modules/core/public/views/pages',
+      'app/modules/core/private/views/pages',
+      'modules/core/public/views/pages',
+      'modules/core/private/views/pages',
+    ]);
+  });
+});
+
+describe('type predicate convenience functions', () => {
+  describe('isPartial', () => {
+    it('returns true for views/partials', () => {
+      expect(isPartial(uri('app/views/partials/header.liquid'))).toBe(true);
+    });
+
+    it('returns true for app/lib', () => {
+      expect(isPartial(uri('app/lib/utils.liquid'))).toBe(true);
+    });
+
+    it('returns true for module lib', () => {
+      expect(isPartial(uri('modules/core/public/lib/utils.liquid'))).toBe(true);
+    });
+
+    it('returns false for pages', () => {
+      expect(isPartial(uri('app/views/pages/home.liquid'))).toBe(false);
+    });
+
+    it('returns false for generator template with /lib/ in path', () => {
+      expect(isPartial(uri('modules/core/generators/command/templates/lib/create.liquid'))).toBe(
+        false,
+      );
+    });
+  });
+
+  describe('isPage', () => {
+    it('returns true for app/views/pages', () => {
+      expect(isPage(uri('app/views/pages/home.liquid'))).toBe(true);
+    });
+
+    it('returns false for layouts', () => {
+      expect(isPage(uri('app/views/layouts/default.liquid'))).toBe(false);
+    });
+  });
+
+  describe('isLayout', () => {
+    it('returns true for app/views/layouts', () => {
+      expect(isLayout(uri('app/views/layouts/default.liquid'))).toBe(true);
+    });
+
+    it('returns true for module layouts', () => {
+      expect(isLayout(uri('modules/core/public/views/layouts/default.liquid'))).toBe(true);
+    });
+
+    it('returns false for pages', () => {
+      expect(isLayout(uri('app/views/pages/home.liquid'))).toBe(false);
+    });
+  });
+
+  it('isAuthorization', () => {
+    expect(isAuthorization(uri('app/authorization_policies/can_edit.liquid'))).toBe(true);
+    expect(isAuthorization(uri('app/lib/can_edit.liquid'))).toBe(false);
+  });
+
+  it('isEmail', () => {
+    expect(isEmail(uri('app/emails/welcome.liquid'))).toBe(true);
+    expect(isEmail(uri('app/lib/emails/welcome.liquid'))).toBe(false);
+  });
+
+  it('isApiCall', () => {
+    expect(isApiCall(uri('app/api_calls/create.liquid'))).toBe(true);
+    expect(isApiCall(uri('app/lib/api_calls/create.liquid'))).toBe(false);
+  });
+
+  it('isSms', () => {
+    expect(isSms(uri('app/smses/notify.liquid'))).toBe(true);
+    expect(isSms(uri('app/lib/smses/notify.liquid'))).toBe(false);
+    expect(isSms(uri('modules/core/public/smses/notify.liquid'))).toBe(true);
+    expect(isSms(uri('modules/core/public/lib/smses/notify.liquid'))).toBe(false);
+  });
+
+  it('isMigration', () => {
+    expect(isMigration(uri('app/migrations/001_init.liquid'))).toBe(true);
+    expect(isMigration(uri('app/lib/migrations/001_init.liquid'))).toBe(false);
+  });
+});

package/src/path-utils.ts

@@ -1,45 +1,191 @@
 /**
- * Utility functions for identifying platformOS file types based on their paths
+ * Utility functions for identifying platformOS file types based on their paths.
+ *
+ * Architecture:
+ * - FILE_TYPE_DIRS is the single source of truth for all platformOS directory names
+ * - getAppPaths() and getModulePaths() generate concrete search paths from FILE_TYPE_DIRS
+ * - TYPE_MATCHERS pre-compiles regexes for fast URI classification
+ * - getFileType() classifies any URI to a PlatformOSFileType
+ * - isPage(), isLayout(), isPartial() etc. are convenience wrappers around getFileType()
+ *
+ * Pattern precision: each type uses exact path segment patterns (/app/{dir}/ or
+ * /(public|private)/{dir}/) so that nested paths don't produce false positives.
+ * For example, app/lib/smses/file.liquid is correctly identified as Partial
+ * (matches /app/lib/), not Sms (does not match /app/smses/).
  */
 
 import { UriString } from './AbstractFileSystem';
 
 /**
- * Checks if a URI points to a partial file.
- * Partials can be located in:
- * - app/lib
- * - app/views/partials
- * - app/modules/{moduleName}/public/lib
- * - app/modules/{moduleName}/private/lib
- * - app/modules/{moduleName}/public/views/partials
- * - app/modules/{moduleName}/private/views/partials
- * - modules/{moduleName}/public/lib
- * - modules/{moduleName}/private/lib
- * - modules/{moduleName}/public/views/partials
- * - modules/{moduleName}/private/views/partials
+ * File types that exist in a platformOS app, each mapping to one or more
+ * canonical directory names relative to the app root or module access level.
  */
-export function isPartial(uri: UriString): boolean {
-  return uri.includes('/lib/') || uri.includes('/views/partials');
+export enum PlatformOSFileType {
+  Page = 'Page',
+  Layout = 'Layout',
+  Partial = 'Partial',
+  Authorization = 'Authorization',
+  Email = 'Email',
+  ApiCall = 'ApiCall',
+  Sms = 'Sms',
+  Migration = 'Migration',
+  GraphQL = 'GraphQL',
+  Asset = 'Asset',
 }
 
 /**
- * Checks if a URI points to a page file.
- * Pages are located in app/views/pages
+ * The single source of truth for the platformOS directory structure.
+ *
+ * Maps each file type to its canonical directory name(s) relative to:
+ *   - the app root:                  app/{dir}/
+ *   - a module access level:         modules/{name}/(public|private)/{dir}/
+ *   - a nested module access level:  app/modules/{name}/(public|private)/{dir}/
+ *
+ * Types with multiple dirs (e.g. Partial) will match any of their dirs.
+ * The first matching type wins, so order of evaluation matters for overlapping
+ * paths — but exact segment matching means dirs don't overlap in practice.
  */
-export function isPage(uri: UriString): boolean {
-  return uri.includes('/views/pages');
+export const FILE_TYPE_DIRS: Readonly<Record<PlatformOSFileType, readonly string[]>> = {
+  [PlatformOSFileType.Page]: ['views/pages'],
+  [PlatformOSFileType.Layout]: ['views/layouts'],
+  [PlatformOSFileType.Partial]: ['views/partials', 'lib'],
+  [PlatformOSFileType.Authorization]: ['authorization_policies'],
+  [PlatformOSFileType.Email]: ['emails'],
+  [PlatformOSFileType.ApiCall]: ['api_calls'],
+  [PlatformOSFileType.Sms]: ['smses'],
+  [PlatformOSFileType.Migration]: ['migrations'],
+  [PlatformOSFileType.GraphQL]: ['graphql'],
+  [PlatformOSFileType.Asset]: ['assets'],
+};
+
+/**
+ * Liquid-containing file types. GraphQL and Asset are excluded because they
+ * don't contain Liquid code and should not be passed to the Liquid linter.
+ */
+const LIQUID_FILE_TYPES = new Set<PlatformOSFileType>([
+  PlatformOSFileType.Page,
+  PlatformOSFileType.Layout,
+  PlatformOSFileType.Partial,
+  PlatformOSFileType.Authorization,
+  PlatformOSFileType.Email,
+  PlatformOSFileType.ApiCall,
+  PlatformOSFileType.Sms,
+  PlatformOSFileType.Migration,
+]);
+
+/**
+ * Pre-compiled regex per file type, derived entirely from FILE_TYPE_DIRS.
+ *
+ * For each canonical dir, two pattern alternatives are generated:
+ *   /app/{dir}/              — direct app-level path (e.g. /app/lib/)
+ *   /(public|private)/{dir}/ — module path, covers both:
+ *                                modules/{name}/(public|private)/{dir}/
+ *                                app/modules/{name}/(public|private)/{dir}/
+ *
+ * Exact path segment matching prevents false positives:
+ *   /app/lib/smses/file.liquid  → matches /app/lib/ → Partial (NOT Sms)
+ *   /app/smses/file.liquid      → matches /app/smses/ → Sms (NOT Partial)
+ */
+const TYPE_MATCHERS = new Map<PlatformOSFileType, RegExp>(
+  (Object.entries(FILE_TYPE_DIRS) as [PlatformOSFileType, readonly string[]][]).map(
+    ([type, dirs]) => {
+      const alternatives = dirs.flatMap((dir) => [`/app/${dir}/`, `/(public|private)/${dir}/`]);
+      return [type, new RegExp(alternatives.join('|'))];
+    },
+  ),
+);
+
+/**
+ * Returns the PlatformOSFileType for the given URI, or undefined if the URI
+ * does not belong to any recognized platformOS directory.
+ *
+ * @example
+ * getFileType('file:///root/app/lib/smses/notify.liquid') // → PlatformOSFileType.Partial
+ * getFileType('file:///root/app/smses/notify.liquid')     // → PlatformOSFileType.Sms
+ * getFileType('file:///root/modules/core/generators/templates/lib/create.liquid') // → undefined
+ */
+export function getFileType(uri: UriString): PlatformOSFileType | undefined {
+  for (const [type, re] of TYPE_MATCHERS) {
+    if (re.test(uri)) return type;
+  }
+  return undefined;
 }
 
 /**
- * Checks if a URI points to a layout file.
- * Layouts are located in app/views/layouts
+ * Returns app-level search paths for a file type (relative to project root).
+ *
+ * @example
+ * getAppPaths(PlatformOSFileType.Partial) // → ['app/views/partials', 'app/lib']
+ * getAppPaths(PlatformOSFileType.GraphQL) // → ['app/graphql']
  */
-export function isLayout(uri: UriString): boolean {
-  return uri.includes('/views/layouts');
+export function getAppPaths(type: PlatformOSFileType): string[] {
+  return FILE_TYPE_DIRS[type].map((dir) => `app/${dir}`);
 }
 
 /**
- * Legacy Shopify terminology - use isPartial instead
- * @deprecated Use isPartial instead
+ * Returns all module search paths for a file type and module name, covering
+ * both app/modules/{name}/... and modules/{name}/... roots, and both
+ * public and private access levels (relative to project root).
+ *
+ * @example
+ * getModulePaths(PlatformOSFileType.Partial, 'core') // → [
+ *   'app/modules/core/public/views/partials',
+ *   'app/modules/core/private/views/partials',
+ *   'modules/core/public/views/partials',
+ *   'modules/core/private/views/partials',
+ *   'app/modules/core/public/lib',
+ *   'app/modules/core/private/lib',
+ *   'modules/core/public/lib',
+ *   'modules/core/private/lib',
+ * ]
  */
-export const isSnippet = isPartial;
+export function getModulePaths(type: PlatformOSFileType, moduleName: string): string[] {
+  return FILE_TYPE_DIRS[type].flatMap((dir) => [
+    `app/modules/${moduleName}/public/${dir}`,
+    `app/modules/${moduleName}/private/${dir}`,
+    `modules/${moduleName}/public/${dir}`,
+    `modules/${moduleName}/private/${dir}`,
+  ]);
+}
+
+/**
+ * Returns true if the URI belongs to a recognized platformOS Liquid directory
+ * and should be linted. Files outside known directories (e.g. generator
+ * templates, build artifacts) return false and are excluded from linting.
+ */
+export function isKnownLiquidFile(uri: UriString): boolean {
+  const type = getFileType(uri);
+  return type !== undefined && LIQUID_FILE_TYPES.has(type);
+}
+
+export function isPartial(uri: UriString): boolean {
+  return getFileType(uri) === PlatformOSFileType.Partial;
+}
+
+export function isPage(uri: UriString): boolean {
+  return getFileType(uri) === PlatformOSFileType.Page;
+}
+
+export function isLayout(uri: UriString): boolean {
+  return getFileType(uri) === PlatformOSFileType.Layout;
+}
+
+export function isAuthorization(uri: UriString): boolean {
+  return getFileType(uri) === PlatformOSFileType.Authorization;
+}
+
+export function isEmail(uri: UriString): boolean {
+  return getFileType(uri) === PlatformOSFileType.Email;
+}
+
+export function isApiCall(uri: UriString): boolean {
+  return getFileType(uri) === PlatformOSFileType.ApiCall;
+}
+
+export function isSms(uri: UriString): boolean {
+  return getFileType(uri) === PlatformOSFileType.Sms;
+}
+
+export function isMigration(uri: UriString): boolean {
+  return getFileType(uri) === PlatformOSFileType.Migration;
+}

package/src/translation-provider/TranslationProvider.ts

@@ -106,6 +106,89 @@ export class TranslationProvider {
     return [undefined, undefined];
   }
 
+  /**
+   * Aggregates ALL translation files for `locale` within `translationBaseUri`.
+   *
+   * Covers two layouts:
+   *  - Single file:  `{base}/{locale}.yml`
+   *  - Split files:  `{base}/{locale}/*.yml`
+   *
+   * Only files whose first YAML key matches `locale` are included, so a file
+   * placed in the wrong directory (or accidentally containing a different
+   * locale) is silently ignored.
+   *
+   * @param contentOverride Optional function called before the filesystem is
+   *   consulted.  Return the file's source string to use it instead of the
+   *   on-disk content, or `undefined` to fall through to the filesystem.
+   *   Used by editor integrations to honour unsaved buffer changes.
+   */
+  async loadAllTranslationsForBase(
+    translationBaseUri: URI,
+    locale: string,
+    contentOverride?: (uri: string) => string | undefined,
+  ): Promise<Record<string, any>> {
+    const merged: Record<string, any> = {};
+
+    const read = async (uri: string): Promise<string | undefined> => {
+      if (contentOverride) {
+        const buffered = contentOverride(uri);
+        if (buffered !== undefined) return buffered;
+      }
+      return this.readFileIfExists(uri);
+    };
+
+    // Strategy A: single locale file ({base}/{locale}.yml)
+    const singleFileUri = Utils.joinPath(translationBaseUri, `${locale}.yml`).toString();
+    const singleContent = await read(singleFileUri);
+    if (singleContent) {
+      const parsed = this.parseTranslationFile(singleContent, locale);
+      if (parsed) this.deepMerge(merged, parsed);
+    }
+
+    // Strategy B: locale directory ({base}/{locale}/*.yml)
+    const localeDirUri = Utils.joinPath(translationBaseUri, locale).toString();
+    const ymlFiles = await this.listYmlFiles(localeDirUri);
+    for (const fileUri of ymlFiles) {
+      const content = await read(fileUri);
+      if (content) {
+        const parsed = this.parseTranslationFile(content, locale);
+        if (parsed) this.deepMerge(merged, parsed);
+      }
+    }
+
+    return merged;
+  }
+
+  /**
+   * Parses a YAML translation file and returns its contents under the locale
+   * key.  Returns `undefined` if the file cannot be parsed or if its first
+   * key does not match `expectedLocale` (guards against mis-placed files).
+   */
+  private parseTranslationFile(
+    content: string,
+    expectedLocale: string,
+  ): Record<string, any> | undefined {
+    try {
+      const data = yaml.load(content) as Record<string, any>;
+      if (!data || typeof data !== 'object') return undefined;
+      const firstKey = Object.keys(data)[0];
+      if (firstKey !== expectedLocale) return undefined;
+      return data[firstKey] ?? undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  private deepMerge(target: Record<string, any>, source: Record<string, any>): void {
+    for (const [key, value] of Object.entries(source)) {
+      if (typeof value === 'object' && value !== null && typeof target[key] === 'object') {
+        this.deepMerge(target[key], value);
+      } else {
+        target[key] = value;
+      }
+    }
+  }
+
   async translate(
     rootUri: URI,
     translationKey: string,