@bleedingdev/modern-js-plugin-i18n 3.2.0-ultramodern.99 → 3.4.0-ultramodern.0

package/src/cli/locales.ts

@@ -0,0 +1,186 @@
+import {
+  getPublicDirRoutePrefixes,
+  normalizePublicDir,
+  normalizePublicDirPath,
+} from '@modern-js/server-core';
+import fs from 'fs';
+import path from 'path';
+import type { BackendOptions } from '../shared/type';
+
+interface NormalizedConfigForLocales {
+  server?: {
+    publicDir?: string | string[];
+  };
+}
+
+export interface DetectedLocalesDirectory {
+  loadPath: string;
+  addPath: string;
+  serverLoadPath: string;
+  serverAddPath: string;
+  serverLoadPaths?: string[];
+  serverAddPaths?: string[];
+}
+
+const LOCALES_RESOURCE_PATTERN = '{{lng}}/{{ns}}.json';
+
+function hasJsonFiles(dirPath: string): boolean {
+  try {
+    if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory()) {
+      return false;
+    }
+    const entries = fs.readdirSync(dirPath);
+    for (const entry of entries) {
+      const entryPath = path.join(dirPath, entry);
+      const stat = fs.statSync(entryPath);
+      if (stat.isFile() && entry.endsWith('.json')) {
+        return true;
+      }
+      if (stat.isDirectory() && hasJsonFiles(entryPath)) {
+        return true;
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+function toPosixPath(filePath: string): string {
+  return filePath.split(path.sep).join(path.posix.sep);
+}
+
+function getPublicDirOutputPath(publicDir: string): string {
+  return normalizePublicDirPath(publicDir);
+}
+
+function buildDetectedLocalesDirectory(
+  clientBasePath: string,
+  serverBasePath: string,
+  serverBasePathCandidates: string[] = [serverBasePath],
+): DetectedLocalesDirectory {
+  const normalizedClientBasePath = clientBasePath.startsWith('/')
+    ? clientBasePath
+    : `/${clientBasePath}`;
+  const normalizedServerBasePath = toPosixPath(serverBasePath).replace(
+    /\/$/,
+    '',
+  );
+  const normalizedServerBasePathCandidates = Array.from(
+    new Set(
+      serverBasePathCandidates.map(candidate =>
+        toPosixPath(candidate).replace(/\/$/, ''),
+      ),
+    ),
+  );
+  const serverLoadPaths = normalizedServerBasePathCandidates.map(
+    candidate => `${candidate}/${LOCALES_RESOURCE_PATTERN}`,
+  );
+  const serverAddPaths = normalizedServerBasePathCandidates.map(
+    candidate => `${candidate}/${LOCALES_RESOURCE_PATTERN}`,
+  );
+
+  return {
+    loadPath: `${normalizedClientBasePath}/${LOCALES_RESOURCE_PATTERN}`,
+    addPath: `${normalizedClientBasePath}/${LOCALES_RESOURCE_PATTERN}`,
+    serverLoadPath: `${normalizedServerBasePath}/${LOCALES_RESOURCE_PATTERN}`,
+    serverAddPath: `${normalizedServerBasePath}/${LOCALES_RESOURCE_PATTERN}`,
+    serverLoadPaths,
+    serverAddPaths,
+  };
+}
+
+export function detectLocalesDirectory(
+  appDirectory: string,
+  normalizedConfig?: NormalizedConfigForLocales,
+): DetectedLocalesDirectory | undefined {
+  const publicDirs = normalizePublicDir(normalizedConfig?.server?.publicDir);
+  const publicDirPrefixes = getPublicDirRoutePrefixes(
+    normalizedConfig?.server?.publicDir,
+  );
+
+  for (let index = 0; index < publicDirs.length; index++) {
+    const publicDir = publicDirs[index];
+    if (path.isAbsolute(publicDir)) {
+      continue;
+    }
+
+    const publicDirPath = path.join(appDirectory, publicDir);
+    const publicDirPrefix =
+      publicDirPrefixes[index] || `/${normalizePublicDirPath(publicDir)}`;
+    const publicDirOutputPath = getPublicDirOutputPath(publicDir);
+
+    if (
+      path.basename(normalizePublicDirPath(publicDir)) === 'locales' &&
+      hasJsonFiles(publicDirPath)
+    ) {
+      return buildDetectedLocalesDirectory(
+        publicDirPrefix,
+        `./${publicDirOutputPath}`,
+      );
+    }
+
+    const localesPath = path.join(publicDirPath, 'locales');
+    if (hasJsonFiles(localesPath)) {
+      return buildDetectedLocalesDirectory(
+        `${publicDirPrefix}/locales`,
+        `./${publicDirOutputPath}/locales`,
+      );
+    }
+  }
+
+  const configPublicPath = path.join(
+    appDirectory,
+    'config',
+    'public',
+    'locales',
+  );
+  if (hasJsonFiles(configPublicPath)) {
+    return buildDetectedLocalesDirectory('/locales', './public/locales', [
+      './config/public/locales',
+      './public/locales',
+    ]);
+  }
+
+  const rootLocalesPath = path.join(appDirectory, 'locales');
+  if (hasJsonFiles(rootLocalesPath)) {
+    return buildDetectedLocalesDirectory('/locales', './locales');
+  }
+
+  return undefined;
+}
+
+export function applyDetectedBackendPaths(
+  backendOptions: BackendOptions,
+  detectedLocales: DetectedLocalesDirectory | undefined,
+): BackendOptions {
+  if (!detectedLocales) {
+    return backendOptions;
+  }
+
+  const backendWithDetectedPaths: BackendOptions & {
+    _detectedLoadPath: string;
+    _detectedAddPath: string;
+  } = {
+    ...backendOptions,
+    enabled: true,
+    loadPath: backendOptions.loadPath ?? detectedLocales.loadPath,
+    addPath: backendOptions.addPath ?? detectedLocales.addPath,
+    serverLoadPath:
+      backendOptions.serverLoadPath ?? detectedLocales.serverLoadPath,
+    serverLoadPaths:
+      backendOptions.serverLoadPath || backendOptions.serverLoadPaths
+        ? backendOptions.serverLoadPaths
+        : detectedLocales.serverLoadPaths,
+    serverAddPath:
+      backendOptions.serverAddPath ?? detectedLocales.serverAddPath,
+    serverAddPaths:
+      backendOptions.serverAddPath || backendOptions.serverAddPaths
+        ? backendOptions.serverAddPaths
+        : detectedLocales.serverAddPaths,
+    _detectedLoadPath: detectedLocales.loadPath,
+    _detectedAddPath: detectedLocales.addPath,
+  };
+
+  return backendWithDetectedPaths;
+}

package/src/runtime/I18nLink.tsx

@@ -1,7 +1,5 @@
 import type React from 'react';
-import { useModernI18n } from './context';
-import { useI18nRouterAdapter } from './routerAdapter';
-import { buildLocalizedUrl } from './utils';
+import { Link } from './Link';
 
 export interface I18nLinkProps {
   to: string;
@@ -9,59 +7,30 @@ export interface I18nLinkProps {
   [key: string]: any;
 }
 
+let warnedDeprecation = false;
+
 /**
- * I18nLink component that automatically adds language prefix to navigation links.
- * This component should be used within a :lang dynamic route context.
- *
- * @example
- * ```tsx
- * // When current language is 'en' and to="/about"
- * // The actual link will be "/en/about"
- * <I18nLink to="/about">About</I18nLink>
- *
- * // When current language is 'zh' and to="/"
- * // The actual link will be "/zh"
- * <I18nLink to="/">Home</I18nLink>
- * ```
+ * @deprecated Use {@link Link} from `@modern-js/plugin-i18n/runtime` instead.
+ * `Link` accepts the same language-agnostic `to` values and additionally
+ * supports `#hash`/`?query` targets, typed canonical routes, `params`
+ * interpolation and language-invariant active state.
  */
 export const I18nLink: React.FC<I18nLinkProps> = ({
   to,
   children,
   ...props
 }) => {
-  const { Link, params, hasRouter } = useI18nRouterAdapter();
-  const { language, supportedLanguages, localisedUrls } = useModernI18n();
-
-  // Get the current language from context (which reflects the actual current language)
-  // URL params might be stale after language changes, so we prioritize the context language
-  const currentLang = language;
-
-  // Build the localized URL by adding language prefix
-  const localizedTo = buildLocalizedUrl(
-    to,
-    currentLang,
-    supportedLanguages,
-    localisedUrls,
-  );
-
-  // In development mode, warn if used outside of :lang route context
-  if (process.env.NODE_ENV === 'development' && hasRouter && !params.lang) {
+  if (process.env.NODE_ENV === 'development' && !warnedDeprecation) {
+    warnedDeprecation = true;
     console.warn(
-      'I18nLink is being used outside of a :lang dynamic route context. ' +
-        'This may cause unexpected behavior. Please ensure I18nLink is used within a route that has a :lang parameter.',
-    );
-  }
-
-  if (!hasRouter || !Link) {
-    return (
-      <a href={localizedTo} {...props}>
-        {children}
-      </a>
+      '[plugin-i18n] I18nLink is deprecated. Import { Link } from ' +
+        "'@modern-js/plugin-i18n/runtime' instead — it accepts the same " +
+        'language-agnostic `to` values.',
     );
   }
 
   return (
-    <Link to={localizedTo} {...props}>
+    <Link to={to} {...props}>
       {children}
     </Link>
   );

package/src/runtime/Link.tsx

@@ -0,0 +1,430 @@
+import type React from 'react';
+import { useMemo } from 'react';
+import type {
+  LinkParamsProp,
+  LinkTargetPathname,
+  ValidateLinkTo,
+} from './canonicalRoutes';
+import { useModernI18n } from './context';
+import { canonicalPath, type LocalizedPathsConfig } from './localizedPaths';
+import { useI18nRouterAdapter } from './routerAdapter';
+import { buildLocalizedUrl, splitUrlTarget } from './utils';
+
+const EXTERNAL_TARGET_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
+
+const warnedTargets = new Set<string>();
+
+const warnOnce = (key: string, message: string) => {
+  if (process.env.NODE_ENV !== 'development' || warnedTargets.has(key)) {
+    return;
+  }
+  warnedTargets.add(key);
+  console.warn(message);
+};
+
+export type LinkParams = Record<string, string | number | undefined>;
+
+/**
+ * Interpolate `$param`, `:param`, optional (`{-$param}` / `:param?`) and splat
+ * (`$` / `*`) segments with concrete values before localization, so
+ * pattern-mapped slugs localize correctly.
+ */
+export const interpolateRouteParams = (
+  pathname: string,
+  params?: LinkParams,
+): string => {
+  if (!/[$:*{]/.test(pathname)) {
+    return pathname;
+  }
+
+  const resolveParam = (name: string): string | undefined => {
+    const value = params?.[name];
+    return value === undefined ? undefined : String(value);
+  };
+
+  const segments = pathname
+    .split('/')
+    .map(segment => {
+      if (!segment) {
+        return segment;
+      }
+
+      if (segment.startsWith('{-$') && segment.endsWith('}')) {
+        const value = resolveParam(segment.slice(3, -1));
+        return value === undefined ? null : encodeURIComponent(value);
+      }
+
+      if (segment === '$' || segment === '*') {
+        const value = resolveParam('_splat') ?? resolveParam('*');
+        return value === undefined
+          ? null
+          : value.split('/').map(encodeURIComponent).join('/');
+      }
+
+      if (segment.startsWith('$')) {
+        const value = resolveParam(segment.slice(1));
+        if (value === undefined) {
+          warnOnce(
+            `missing-param:${pathname}:${segment}`,
+            `[plugin-i18n] <Link to="${pathname}"> is missing required param "${segment.slice(1)}".`,
+          );
+          return segment;
+        }
+        return encodeURIComponent(value);
+      }
+
+      if (segment.startsWith(':')) {
+        const optional = segment.endsWith('?');
+        const name = segment.slice(1, optional ? -1 : undefined);
+        const value = resolveParam(name);
+        if (value === undefined) {
+          if (optional) {
+            return null;
+          }
+          warnOnce(
+            `missing-param:${pathname}:${segment}`,
+            `[plugin-i18n] <Link to="${pathname}"> is missing required param "${name}".`,
+          );
+          return segment;
+        }
+        return encodeURIComponent(value);
+      }
+
+      return segment;
+    })
+    .filter(segment => segment !== null);
+
+  return segments.join('/') || '/';
+};
+
+export interface LinkActiveOptions {
+  /**
+   * `true`: active only when the location matches the target exactly.
+   * `false`: also active when the location is nested under the target.
+   * Defaults to prefix matching, except for `/` which defaults to exact.
+   */
+  exact?: boolean;
+}
+
+type AnchorRest = Omit<
+  React.AnchorHTMLAttributes<HTMLAnchorElement>,
+  'href' | 'children'
+>;
+
+export interface LinkBaseProps extends AnchorRest {
+  children?: React.ReactNode;
+  /** Hash fragment without the leading `#`. Overrides a `#hash` inside `to`. */
+  hash?: string;
+  /** Search params. Object form is passed natively to TanStack Link. */
+  search?: string | Record<string, unknown>;
+  hashScrollIntoView?: boolean | ScrollIntoViewOptions;
+  replace?: boolean;
+  /**
+   * Prefetching behavior, forwarded to the underlying router link:
+   * react-router gets it verbatim (Modern.js `PrefetchLink` supports it),
+   * TanStack receives it as its native `preload` prop (`'none'` -> `false`).
+   * Stripped from plain `<a>` fallbacks (external / no-router targets).
+   */
+  prefetch?: 'intent' | 'render' | 'viewport' | 'none';
+  /**
+   * Native preload value of the underlying router link. When set, it wins
+   * over `prefetch` on the TanStack branch.
+   */
+  preload?: unknown;
+  activeOptions?: LinkActiveOptions;
+  /** Extra anchor props applied when the link is active. */
+  activeProps?: AnchorRest & Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export type LinkProps<TTo extends string = string> = LinkBaseProps & {
+  to: TTo;
+} & ValidateLinkTo<TTo> &
+  LinkParamsProp<LinkTargetPathname<TTo>>;
+
+const normalizeSearch = (
+  search: string | Record<string, unknown> | undefined,
+  searchFromTo: string,
+): {
+  searchString: string;
+  searchObject: Record<string, string> | undefined;
+} => {
+  if (search && typeof search === 'object') {
+    const entries = Object.entries(search).filter(
+      ([, value]) => value !== undefined && value !== null,
+    );
+    const searchObject = Object.fromEntries(
+      entries.map(([key, value]) => [key, String(value)]),
+    );
+    const params = new URLSearchParams(searchObject);
+    const serialized = params.toString();
+    return {
+      searchString: serialized ? `?${serialized}` : '',
+      searchObject,
+    };
+  }
+
+  const raw = typeof search === 'string' && search ? search : searchFromTo;
+  if (!raw) {
+    return { searchString: '', searchObject: undefined };
+  }
+
+  const searchString = raw.startsWith('?') ? raw : `?${raw}`;
+  const searchObject: Record<string, string> = {};
+  new URLSearchParams(searchString).forEach((value, key) => {
+    searchObject[key] = value;
+  });
+
+  return { searchString, searchObject };
+};
+
+const splitActiveProps = (
+  active: boolean,
+  activeProps?: LinkBaseProps['activeProps'],
+) => {
+  if (!active || !activeProps) {
+    return {};
+  }
+  return activeProps;
+};
+
+const mergeClassNames = (...values: Array<unknown>): string | undefined => {
+  const classNames = values.filter(
+    (value): value is string => typeof value === 'string' && value.length > 0,
+  );
+  return classNames.length > 0 ? classNames.join(' ') : undefined;
+};
+
+/**
+ * The standard UltraModern link: a vanilla link in every respect except that
+ * it localizes canonical, language-agnostic paths automatically.
+ *
+ * - `to` accepts canonical routes (`/talks/$slug`), optionally with `#hash`
+ *   and `?query` suffixes; both survive localization.
+ * - External URLs and bare `#hash` targets render a plain `<a>`.
+ * - Active state is language-invariant: a canonical `to` is active when the
+ *   current location matches any localized variant of that route.
+ *
+ * @example
+ * ```tsx
+ * <Link to="/talks/$slug" params={{ slug: talk.slug }} hash="abstract" />
+ * <Link to="/platform" />            // -> /cs/platforma under cs
+ * <Link to="/#work-with-me" />       // cross-page hash, SPA navigation
+ * <Link to="https://ai.bleeding.dev" /> // external -> plain <a>
+ * ```
+ */
+export const Link = <TTo extends string = string>(
+  props: LinkProps<TTo>,
+): React.ReactElement => {
+  const {
+    to,
+    params,
+    children,
+    hash: hashProp,
+    search: searchProp,
+    hashScrollIntoView,
+    activeOptions,
+    activeProps,
+    prefetch,
+    preload,
+    ...rest
+  } = props as LinkBaseProps & { to: string; params?: LinkParams };
+
+  const adapter = useI18nRouterAdapter();
+  const { language, supportedLanguages, localisedUrls } = useModernI18n();
+
+  const config: LocalizedPathsConfig = {
+    languages: supportedLanguages,
+    localisedUrls,
+  };
+
+  const isExternal = EXTERNAL_TARGET_RE.test(to);
+  const isBareHash = to.startsWith('#');
+
+  const target = useMemo(() => {
+    if (isExternal || isBareHash) {
+      return null;
+    }
+
+    const {
+      pathname,
+      search: searchFromTo,
+      hash: hashFromTo,
+    } = splitUrlTarget(to);
+    const interpolated = interpolateRouteParams(pathname || '/', params);
+
+    const firstSegment = interpolated.split('/').filter(Boolean)[0];
+    if (firstSegment && supportedLanguages.includes(firstSegment)) {
+      warnOnce(
+        `lang-prefix:${to}`,
+        `[plugin-i18n] <Link to="${to}"> starts with a language prefix. ` +
+          'Write language-agnostic canonical paths; the Link localizes them automatically.',
+      );
+    }
+
+    const localizedPathname = buildLocalizedUrl(
+      interpolated,
+      language,
+      supportedLanguages,
+      localisedUrls,
+    );
+    const hash = hashProp ?? (hashFromTo ? hashFromTo.slice(1) : '');
+    const { searchString, searchObject } = normalizeSearch(
+      searchProp,
+      searchFromTo,
+    );
+
+    return {
+      canonicalPathname: interpolated,
+      localizedPathname,
+      hash,
+      searchString,
+      searchObject,
+      href: `${localizedPathname}${searchString}${hash ? `#${hash}` : ''}`,
+    };
+  }, [
+    to,
+    params,
+    hashProp,
+    searchProp,
+    isExternal,
+    isBareHash,
+    language,
+    supportedLanguages,
+    localisedUrls,
+  ]);
+
+  const isActive = useMemo(() => {
+    if (!target || !adapter.location) {
+      return false;
+    }
+
+    const current = canonicalPath(adapter.location.pathname, config);
+    const targetCanonical = canonicalPath(target.canonicalPathname, config);
+    const exact = activeOptions?.exact ?? targetCanonical === '/';
+
+    if (current === targetCanonical) {
+      return true;
+    }
+    if (exact) {
+      return false;
+    }
+    return current.startsWith(
+      targetCanonical === '/' ? '/' : `${targetCanonical}/`,
+    );
+  }, [
+    target,
+    adapter.location,
+    activeOptions?.exact,
+    supportedLanguages,
+    localisedUrls,
+  ]);
+
+  const resolvedActiveProps = splitActiveProps(isActive, activeProps);
+  const activeAttributes = isActive
+    ? {
+        'data-status': 'active',
+        'aria-current': (rest['aria-current'] ??
+          resolvedActiveProps['aria-current'] ??
+          'page') as React.AriaAttributes['aria-current'],
+      }
+    : {};
+
+  // External targets and same-page anchors are vanilla links.
+  if (!target) {
+    const { replace: _replace, ...anchorProps } = rest;
+
+    return (
+      <a href={to} {...anchorProps}>
+        {children}
+      </a>
+    );
+  }
+
+  const { Link: RouterLink, hasRouter, framework } = adapter;
+
+  if (!hasRouter || !RouterLink) {
+    const { replace: _replace, ...anchorProps } = rest;
+    const {
+      className: activeClassName,
+      style: activeStyle,
+      ...activeRest
+    } = resolvedActiveProps;
+
+    return (
+      <a
+        href={target.href}
+        {...anchorProps}
+        {...activeRest}
+        {...activeAttributes}
+        className={mergeClassNames(rest.className, activeClassName)}
+        style={{
+          ...(rest.style as React.CSSProperties | undefined),
+          ...(activeStyle as React.CSSProperties | undefined),
+        }}
+      >
+        {children}
+      </a>
+    );
+  }
+
+  const {
+    className: activeClassName,
+    style: activeStyle,
+    ...activeRest
+  } = resolvedActiveProps;
+  const mergedClassName = mergeClassNames(rest.className, activeClassName);
+  const mergedStyle = {
+    ...(rest.style as React.CSSProperties | undefined),
+    ...(activeStyle as React.CSSProperties | undefined),
+  };
+
+  if (framework === 'tanstack') {
+    // TanStack's prop is `preload`; map our react-router-flavored `prefetch`
+    // onto it (`'none'` -> `false`). An explicit native `preload` wins.
+    const tanstackPreload =
+      preload !== undefined
+        ? preload
+        : prefetch === undefined
+          ? undefined
+          : prefetch === 'none'
+            ? false
+            : prefetch;
+
+    // Pass hash/search natively: string-concatenated targets silently break
+    // TanStack navigation.
+    return (
+      <RouterLink
+        to={target.localizedPathname}
+        {...(target.searchObject ? { search: target.searchObject } : {})}
+        {...(target.hash ? { hash: target.hash } : {})}
+        {...(hashScrollIntoView === undefined ? {} : { hashScrollIntoView })}
+        {...(tanstackPreload === undefined ? {} : { preload: tanstackPreload })}
+        {...rest}
+        {...activeRest}
+        {...activeAttributes}
+        className={mergedClassName}
+        style={mergedStyle}
+      >
+        {children}
+      </RouterLink>
+    );
+  }
+
+  return (
+    <RouterLink
+      to={target.href}
+      {...(prefetch === undefined ? {} : { prefetch })}
+      {...(preload === undefined ? {} : { preload })}
+      {...rest}
+      {...activeRest}
+      {...activeAttributes}
+      className={mergedClassName}
+      style={mergedStyle}
+    >
+      {children}
+    </RouterLink>
+  );
+};
+
+export default Link;