Localization

Filter Sphere provides a variety of ways to localize the UI. This is useful when you want to display the UI in a different language.

Built-in Locales

Filter Sphere provides some built-in locales. You can import them from the @fn-sphere/filter/locales module.

Locale	Import name
English	`enUS`
Japanese	`jaJP`
Chinese (Simplified)	`zhCN`

import { enUS, jaJP, zhCN } from "@fn-sphere/filter/locales";

const locale = enUS;

const customGetLocaleText = (key: string): string => {
  if (!(key in locale)) return key;
  return locale[key as keyof typeof locale];
};

export default function AdvancedFilter() {
  const { filterRule, predicate, context } = useFilterSphere({
    schema,
    getLocaleText: customGetLocaleText,
  });
  return (
    <FilterSphereProvider context={context}>
      <FilterBuilder />
    </FilterSphereProvider>
  );
}

getLocaleText

The default locale of Filter Sphere is English (United States). You can use the getLocaleText function to translate the filter UI.

import {
  FilterSphereProvider,
  FilterBuilder,
  useFilterSphere,
} from "@fn-sphere/filter";
import { enUS, jaJP, zhCN } from "@fn-sphere/filter/locales";
import { z } from "zod";
import { useState } from "react";

const locales = [
  { key: "cn", label: "中文", value: { ...zhCN, price: "价格", name: "名称" } },
  {
    key: "jp",
    label: "日本語",
    value: { ...jaJP, price: "価格", name: "名前" },
  },
  { key: "en", label: "English", value: enUS },
];

const schema = z.object({
  name: z.string(),
  price: z.number(),
});

export default function AdvancedFilter() {
  const [localeKey, setLocaleKey] = useState("cn");

  const customGetLocaleText = (key: string): string => {
    const locale = locales.find((locale) => locale.key === localeKey)?.value;
    if (!locale || !(key in locale)) return key;
    return locale[key as keyof typeof locale];
  };

  const { filterRule, predicate, context } = useFilterSphere({
    schema,
    getLocaleText: customGetLocaleText,
  });
  return (
    <FilterSphereProvider context={context}>
      <select onChange={(e) => setLocaleKey(e.target.value)}>
        {locales.map((locale) => (
          <option key={locale.key} value={locale.key}>
            {locale.label}
          </option>
        ))}
      </select>
      <FilterBuilder />
    </FilterSphereProvider>
  );
}

mapFieldName / mapFilterName

You can customize the field name and filter name by providing the mapFieldName and mapFilterName functions.

import {
  FilterSphereProvider,
  FilterBuilder,
  useFilterSphere,
} from "@fn-sphere/filter";
import { z } from "zod";

const customMapFieldName = (field: FilterField) => {
  return field.fieldSchema.description;
};

const customMapFilterName = (filterSchema: StandardFnSchema) => {
  return filterSchema.name.toUpperCase();
};

const schema = z.object({
  id: z.number().describe("ID"),
  name: z.string().describe("Name"),
});

export default function AdvancedFilter() {
  const { filterRule, predicate, context } = useFilterSphere({
    schema,
    mapFilterName: customMapFilterName,
    mapFieldName: customMapFieldName,
  });
  return (
    <FilterSphereProvider context={context}>
      <FilterBuilder />
    </FilterSphereProvider>
  );
}

Filter Sphere provides default implementations for the mapFieldName and mapFilterName functions.

export const defaultMapFieldName: (field: FilterField) => string = (field) => {
  // By default, filter sphere uses the field description as the field name.
  if (field.fieldSchema.description) {
    return field.fieldSchema.description;
  }
  // If the field description is not provided, the field path is used as the field name.
  if (field.path.length) {
    return field.path.join(".");
  }
  return "root";
};

export const defaultMapFilterName: (
  filterSchema: StandardFnSchema,
  field: FilterField,
) => string = (filterSchema) => {
  return filterSchema.name;
};