@rocapine/community-core 0.2.0 → 0.5.0

package/README.md

@@ -38,6 +38,10 @@ const config: CommunityConfig = {
     push: false,
     inbox: true,
     reaction: { key: "cheer" }, // or `false` to disable the reaction module
+    // posts/comments/poll labels translated at publication into these
+    // locales — must equal the backend's COMMUNITY_TRANSLATION_LOCALES.
+    // Absent or `false` ⇒ every query and screen behaves as before.
+    translation: { locales: ["en", "es-419"] },
   },
 
   // Host adapters — every field optional, no-op defaults.
@@ -69,14 +73,14 @@ backend configured — the pattern `examples/expo-app` uses when
 
 All optional, all default to a no-op:
 
-| Field                | Signature                                                | Purpose                                                                                                                                                                               |
-| -------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `getDisplayName`     | `() => string \| null`                                   | Feeds the display name shown for the current user before their community username is set                                                                                              |
-| `getAnalyticsIds`    | `() => { amplitudeId?: string; revenuecatId?: string }`  | Cross-referencing ids attached where the host wants them                                                                                                                              |
-| `onEvent`            | `(name: string, props: Record<string, unknown>) => void` | **The only analytics seam.** Every product event goes through this; the SDK never depends on any analytics provider. Never throws through to the UI even if the adapter itself throws |
-| `rulesAcceptance`    | `{ get(): Promise<boolean>; set(): Promise<void> }`      | Persists whether the user has accepted the one-time community guidelines sheet                                                                                                        |
-| `onContentPublished` | `() => void`                                             | Fired after a post/comment is successfully published (e.g. to arm a review-gate)                                                                                                      |
-| `getLocale`          | `() => string`                                           | Selects which locale-specific behavior the _host_ wants (distinct from the UI package's own `translations.locale` prop)                                                               |
+| Field                | Signature                                                | Purpose                                                                                                                                                                                                                                                                                                             |
+| -------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getDisplayName`     | `() => string \| null`                                   | Feeds the display name shown for the current user before their community username is set                                                                                                                                                                                                                            |
+| `getAnalyticsIds`    | `() => { amplitudeId?: string; revenuecatId?: string }`  | Cross-referencing ids attached where the host wants them                                                                                                                                                                                                                                                            |
+| `onEvent`            | `(name: string, props: Record<string, unknown>) => void` | **The only analytics seam.** Every product event goes through this; the SDK never depends on any analytics provider. Never throws through to the UI even if the adapter itself throws                                                                                                                               |
+| `rulesAcceptance`    | `{ get(): Promise<boolean>; set(): Promise<void> }`      | Persists whether the user has accepted the one-time community guidelines sheet                                                                                                                                                                                                                                      |
+| `onContentPublished` | `() => void`                                             | Fired after a post/comment is successfully published (e.g. to arm a review-gate)                                                                                                                                                                                                                                    |
+| `getLocale`          | `() => string`                                           | The app's language. Resolved against `modules.translation.locales` to choose the language content is read in (`readerLocale`), and mirrored to `profiles.locale` by `syncProfileFromHost` so pushes arrive in each recipient's language. Distinct from the UI package's `translations.locale` prop (interface copy) |
 
 ### Feed row extension point (`CommunityConfig.feed`)
 
@@ -128,7 +132,8 @@ import { COMMUNITY_EVENTS, type CommunityEventName } from "@rocapine/community-c
 `COMMUNITY_EVENTS` is a frozen map of stable event-name strings — `opened`,
 `rulesAccepted`, `postPublished`, `pollVoted`, `threadOpened`, `postLiked`,
 `commentPublished`, `profileOpened`, `profileUpdated`, `reactionAdded`,
-`userReported`, `userBlocked`, `contentDeleted`, `inboxOpened` — forwarded to
+`userReported`, `userBlocked`, `contentDeleted`, `inboxOpened`,
+`translationToggled` (`community_translation_toggled`, props `{ postId | commentId, to: "original" | "translation" }`) — forwarded to
 `host.onEvent` by the exported `emitEvent(cfg, name, props)` helper. Route or
 ignore these in your own tracking plan; nothing else in the package calls an
 analytics provider directly.
@@ -148,7 +153,16 @@ runs in production and is silent in degraded mode.
   `ReactionData`, and DB-mirroring constants `FEED_PAGE_SIZE`,
   `POST_MAX_LENGTH` (2000), `COMMENT_MAX_LENGTH` (1000), `POLL_MIN_OPTIONS`
   (2), `POLL_MAX_OPTIONS` (4), `POLL_OPTION_MAX_LENGTH` (60) — client-side
-  mirrors of the backend's check constraints.
+  mirrors of the backend's check constraints. `FeedPost.translation` /
+  `ThreadComment.translation` are `{ text, sourceLocale } | null` (embedded
+  only when the translation module is on and the reader locale resolves);
+  `text`/`content` always stay the original. Poll options carry
+  `translatedLabel: string | null` alongside the original `label`.
+- **Locale** (`locale.ts`): `readerLocale(cfg)` — the locale translations
+  are read in (the host's `getLocale()` resolved against
+  `modules.translation.locales`), or `null` when the module is off or
+  nothing resolves. `languageOf(locale)` — the bare-language prefix of a
+  locale tag (e.g. `"es-419"` → `"es"`).
 - **Identity**: `ensureIdentity()`, `resetIdentity()`, `syncProfileFromHost()`
   — anonymous Supabase auth session management.
 - **Queries** (`service.ts`): `fetchFeedPage`, `countNewPosts`, `fetchProfile`,
@@ -163,8 +177,9 @@ runs in production and is silent in degraded mode.
   `useCreateComment`, `useToggleLike`, `useVotePoll`, `useReactToPost`,
   `useReport`, `useBlockUser`, `useDeleteContent`.
 - **Inbox** (opt-in via `modules.inbox`): `fetchInbox`, `markInboxSeen`,
-  `unreadCount`, and hooks `useNotificationInbox`,
-  `useUnreadNotificationCount`, `useMarkInboxSeen`.
+  `unreadCount`, `localizeExcerpts` (swaps a notification's excerpt for its
+  reader-locale translation when one is available), and hooks
+  `useNotificationInbox`, `useUnreadNotificationCount`, `useMarkInboxSeen`.
 - **`timeAgo(iso, nowMs)`** — hardcoded-English relative-time formatting, kept for
   back-compat. **`timeAgoParts(iso, nowMs)`** — the language-free unit+value
   decomposition the UI package actually localizes through its own catalog

package/lib/config.d.ts

@@ -11,6 +11,12 @@ export type CommunityModules = {
     reaction: {
         key: string;
     } | false;
+    /** Translation module: posts/comments/poll labels translated at publication
+     * into these locales (must equal the backend's COMMUNITY_TRANSLATION_LOCALES
+     * secret). Absent or false ⇒ every query and screen behaves as before. */
+    translation?: {
+        locales: string[];
+    } | false;
 };
 export type CommunityHostAdapters = {
     getDisplayName?: () => string | null;

package/lib/events.d.ts

@@ -14,6 +14,7 @@ export declare const COMMUNITY_EVENTS: {
     readonly userBlocked: "user_blocked";
     readonly contentDeleted: "content_deleted";
     readonly inboxOpened: "notification_center_opened";
+    readonly translationToggled: "community_translation_toggled";
 };
 export type CommunityEventName = (typeof COMMUNITY_EVENTS)[keyof typeof COMMUNITY_EVENTS];
 /** Forwards to the host's onEvent adapter. Never throws — a bad adapter must never break the UI. */

package/lib/events.js

@@ -21,6 +21,7 @@ exports.COMMUNITY_EVENTS = {
     userBlocked: "user_blocked",
     contentDeleted: "content_deleted",
     inboxOpened: "notification_center_opened",
+    translationToggled: "community_translation_toggled",
 };
 /** Forwards to the host's onEvent adapter. Never throws — a bad adapter must never break the UI. */
 function emitEvent(cfg, name, props) {

package/lib/hooks.d.ts

@@ -1,6 +1,21 @@
-import { type InfiniteData } from "@tanstack/react-query";
+import { type InfiniteData, type QueryClient } from "@tanstack/react-query";
 import { type CommunityProfile, type FeedPost, type ThreadComment } from "./models";
 import { type ModerationVerdict, type ReportInput, type UpdateProfileInput, type UpdateProfileResult } from "./service";
+/** True while a post/comment is still the optimistic placeholder inserted by
+ * `useCreatePost`/`useCreateComment` (its temp id is swapped for the real one
+ * once moderation answers). Server actions keyed on the id (reactions, likes,
+ * votes) must wait until this is false. */
+export declare function isOptimistic(item: {
+    id: string;
+}): boolean;
+/** Our own author fields for an optimistic row, read from the query cache
+ * (`useMyUid` + `useProfile`), so the placeholder links to our profile and
+ * shows our avatar instead of an empty author until the next refetch. */
+export declare function ownAuthorFields(queryClient: QueryClient): {
+    authorId: string;
+    authorHandle: string | null;
+    authorAvatarUrl: string | null;
+};
 type PostCacheEntry = [readonly unknown[], InfiniteData<FeedPost[]> | undefined];
 /**
  * Snapshot of every post-holding cache, for optimistic-update rollback on

package/lib/hooks.js

@@ -10,6 +10,8 @@
 // `applyReaction`) and unseen-count hook (parameterized on `lastSeenAtIso` instead of
 // reading that host's own store). No React Native / analytics-SDK / store imports here.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isOptimistic = isOptimistic;
+exports.ownAuthorFields = ownAuthorFields;
 exports.useCommunityFeed = useCommunityFeed;
 exports.useSearchPosts = useSearchPosts;
 exports.useNewPostsCount = useNewPostsCount;
@@ -30,16 +32,32 @@ exports.useDeleteContent = useDeleteContent;
 const react_query_1 = require("@tanstack/react-query");
 const events_1 = require("./events");
 const identity_1 = require("./identity");
+const keys_1 = require("./keys");
+const locale_1 = require("./locale");
 const models_1 = require("./models");
 const provider_1 = require("./provider");
 const service_1 = require("./service");
-const FEED_KEY = ["community", "feed"];
-const feedKey = (topic) => [...FEED_KEY, topic ?? "all"];
-const threadKey = (postId) => ["community", "thread", postId];
 const profileKey = (userId) => ["community", "profile", userId];
-const userPostsKey = (userId) => ["community", "userPosts", userId];
-const USER_POSTS_KEY = ["community", "userPosts"];
-const SEARCH_KEY = ["community", "search"];
+const MY_UID_KEY = ["community", "myUid"];
+/** True while a post/comment is still the optimistic placeholder inserted by
+ * `useCreatePost`/`useCreateComment` (its temp id is swapped for the real one
+ * once moderation answers). Server actions keyed on the id (reactions, likes,
+ * votes) must wait until this is false. */
+function isOptimistic(item) {
+    return item.id.startsWith("optimistic-");
+}
+/** Our own author fields for an optimistic row, read from the query cache
+ * (`useMyUid` + `useProfile`), so the placeholder links to our profile and
+ * shows our avatar instead of an empty author until the next refetch. */
+function ownAuthorFields(queryClient) {
+    const uid = queryClient.getQueryData(MY_UID_KEY) ?? "";
+    const profile = uid ? queryClient.getQueryData(profileKey(uid)) : undefined;
+    return {
+        authorId: uid,
+        authorHandle: profile?.handle ?? null,
+        authorAvatarUrl: profile?.avatarUrl ?? null,
+    };
+}
 /**
  * Adjust a post's commentCount across every cached feed page (all topic
  * filters). The feed is never refetched after commenting (kept smooth), so the
@@ -48,7 +66,7 @@ const SEARCH_KEY = ["community", "search"];
  * change is not reflected in the user-posts/search caches, same as upstream.
  */
 function bumpFeedCommentCount(queryClient, postId, delta) {
-    queryClient.setQueriesData({ queryKey: FEED_KEY }, (data) => data
+    queryClient.setQueriesData({ queryKey: keys_1.FEED_KEY }, (data) => data
         ? {
             ...data,
             pages: data.pages.map((page) => page.map((post) => post.id === postId
@@ -67,19 +85,19 @@ function bumpFeedCommentCount(queryClient, postId, delta) {
  */
 async function applyOptimisticToAllPostCaches(queryClient, mapPost) {
     await Promise.all([
-        queryClient.cancelQueries({ queryKey: FEED_KEY }),
-        queryClient.cancelQueries({ queryKey: USER_POSTS_KEY }),
-        queryClient.cancelQueries({ queryKey: SEARCH_KEY }),
+        queryClient.cancelQueries({ queryKey: keys_1.FEED_KEY }),
+        queryClient.cancelQueries({ queryKey: keys_1.USER_POSTS_KEY }),
+        queryClient.cancelQueries({ queryKey: keys_1.SEARCH_KEY }),
     ]);
     const entries = [
-        ...queryClient.getQueriesData({ queryKey: FEED_KEY }),
-        ...queryClient.getQueriesData({ queryKey: USER_POSTS_KEY }),
-        ...queryClient.getQueriesData({ queryKey: SEARCH_KEY }),
+        ...queryClient.getQueriesData({ queryKey: keys_1.FEED_KEY }),
+        ...queryClient.getQueriesData({ queryKey: keys_1.USER_POSTS_KEY }),
+        ...queryClient.getQueriesData({ queryKey: keys_1.SEARCH_KEY }),
     ];
     const applyToPages = (data) => data ? { ...data, pages: data.pages.map((page) => page.map(mapPost)) } : data;
-    queryClient.setQueriesData({ queryKey: FEED_KEY }, applyToPages);
-    queryClient.setQueriesData({ queryKey: USER_POSTS_KEY }, applyToPages);
-    queryClient.setQueriesData({ queryKey: SEARCH_KEY }, applyToPages);
+    queryClient.setQueriesData({ queryKey: keys_1.FEED_KEY }, applyToPages);
+    queryClient.setQueriesData({ queryKey: keys_1.USER_POSTS_KEY }, applyToPages);
+    queryClient.setQueriesData({ queryKey: keys_1.SEARCH_KEY }, applyToPages);
     return { entries };
 }
 function rollbackPostCaches(queryClient, snapshot) {
@@ -94,8 +112,9 @@ function rollbackPostCaches(queryClient, snapshot) {
  */
 function useCommunityFeed(topic, enabled = true) {
     const cfg = (0, provider_1.useCommunityConfig)();
+    const locale = (0, locale_1.readerLocale)(cfg);
     return (0, react_query_1.useInfiniteQuery)({
-        queryKey: feedKey(topic),
+        queryKey: (0, keys_1.feedKey)(topic, locale),
         queryFn: ({ pageParam }) => (0, service_1.fetchFeedPage)(cfg, { topic, cursor: pageParam }),
         initialPageParam: 0,
         getNextPageParam: (lastPage, pages) => lastPage.length === models_1.FEED_PAGE_SIZE ? pages.length : undefined,
@@ -111,8 +130,9 @@ function useCommunityFeed(topic, enabled = true) {
 function useSearchPosts(term) {
     const cfg = (0, provider_1.useCommunityConfig)();
     const cleaned = term.trim();
+    const locale = (0, locale_1.readerLocale)(cfg);
     return (0, react_query_1.useInfiniteQuery)({
-        queryKey: [...SEARCH_KEY, cleaned],
+        queryKey: (0, keys_1.searchKey)(cleaned, locale),
         queryFn: ({ pageParam }) => (0, service_1.searchPosts)(cfg, cleaned, { cursor: pageParam }),
         initialPageParam: 0,
         getNextPageParam: (lastPage, pages) => lastPage.length === models_1.FEED_PAGE_SIZE ? pages.length : undefined,
@@ -163,8 +183,9 @@ function useCommunityUnseenCount(lastSeenAtIso) {
 }
 function useThread(postId) {
     const cfg = (0, provider_1.useCommunityConfig)();
+    const locale = (0, locale_1.readerLocale)(cfg);
     return (0, react_query_1.useQuery)({
-        queryKey: threadKey(postId ?? "none"),
+        queryKey: (0, keys_1.threadKey)(postId ?? "none", locale),
         queryFn: () => (0, service_1.fetchThread)(cfg, postId),
         enabled: cfg.supabase !== null && !!postId,
         staleTime: 1000 * 15,
@@ -186,8 +207,9 @@ function useProfile(userId) {
  */
 function useUserPosts(userId) {
     const cfg = (0, provider_1.useCommunityConfig)();
+    const locale = (0, locale_1.readerLocale)(cfg);
     return (0, react_query_1.useInfiniteQuery)({
-        queryKey: userPostsKey(userId ?? "none"),
+        queryKey: (0, keys_1.userPostsKey)(userId ?? "none", locale),
         queryFn: ({ pageParam }) => (0, service_1.fetchUserPosts)(cfg, userId, { cursor: pageParam }),
         initialPageParam: 0,
         getNextPageParam: (lastPage, pages) => lastPage.length === models_1.FEED_PAGE_SIZE ? pages.length : undefined,
@@ -200,7 +222,7 @@ function useUserPosts(userId) {
 function useMyUid() {
     const cfg = (0, provider_1.useCommunityConfig)();
     const q = (0, react_query_1.useQuery)({
-        queryKey: ["community", "myUid"],
+        queryKey: MY_UID_KEY,
         queryFn: () => (0, identity_1.ensureIdentity)(cfg),
         enabled: cfg.supabase !== null,
         staleTime: Infinity,
@@ -235,17 +257,16 @@ function useUpdateProfile() {
 function useCreatePost() {
     const cfg = (0, provider_1.useCommunityConfig)();
     const queryClient = (0, react_query_1.useQueryClient)();
+    const locale = (0, locale_1.readerLocale)(cfg);
     return (0, react_query_1.useMutation)({
         onMutate: async ({ topic, text, authorName, pollOptions }) => {
-            await queryClient.cancelQueries({ queryKey: FEED_KEY });
+            await queryClient.cancelQueries({ queryKey: keys_1.FEED_KEY });
             const tempId = `optimistic-${Date.now()}`;
             const optimistic = {
                 id: tempId,
-                authorId: "",
                 authorName,
                 authorOfficial: false,
-                authorHandle: null,
-                authorAvatarUrl: null,
+                ...ownAuthorFields(queryClient),
                 topic,
                 text,
                 status: "visible",
@@ -259,7 +280,12 @@ function useCreatePost() {
                 // refetch below swaps in the real uuids.
                 poll: pollOptions && pollOptions.length > 0
                     ? {
-                        options: pollOptions.map((label, i) => ({ id: `temp-${i}`, label, votes: 0 })),
+                        options: pollOptions.map((label, i) => ({
+                            id: `temp-${i}`,
+                            label,
+                            translatedLabel: null,
+                            votes: 0,
+                        })),
                         myOptionId: null,
                         totalVotes: 0,
                     }
@@ -267,10 +293,11 @@ function useCreatePost() {
                 reactionCount: 0,
                 hasReacted: false,
                 lastReactorName: null,
+                translation: null,
             };
             const prepend = (key) => queryClient.setQueryData(key, (d) => d ? { ...d, pages: [[optimistic, ...(d.pages[0] ?? [])], ...d.pages.slice(1)] } : d);
-            prepend(feedKey(undefined));
-            prepend(feedKey(topic));
+            prepend((0, keys_1.feedKey)(undefined, locale));
+            prepend((0, keys_1.feedKey)(topic, locale));
             return { tempId };
         },
         mutationFn: async ({ topic, text, pollOptions }) => {
@@ -280,7 +307,7 @@ function useCreatePost() {
         },
         onSuccess: ({ id, verdict }, { topic, text, pollOptions }, { tempId }) => {
             const rejected = verdict.status === "rejected";
-            queryClient.setQueriesData({ queryKey: FEED_KEY }, (d) => d
+            queryClient.setQueriesData({ queryKey: keys_1.FEED_KEY }, (d) => d
                 ? {
                     ...d,
                     pages: d.pages.map((p) => rejected
@@ -299,11 +326,11 @@ function useCreatePost() {
                 // The in-place swap above keeps the optimistic poll's temp option ids;
                 // voting needs the real uuids, so a poll post refetches in background.
                 if (hasPoll)
-                    queryClient.invalidateQueries({ queryKey: FEED_KEY });
+                    queryClient.invalidateQueries({ queryKey: keys_1.FEED_KEY });
             }
         },
         onError: (_e, _v, context) => {
-            queryClient.setQueriesData({ queryKey: FEED_KEY }, (d) => d
+            queryClient.setQueriesData({ queryKey: keys_1.FEED_KEY }, (d) => d
                 ? { ...d, pages: d.pages.map((p) => p.filter((post) => post.id !== context?.tempId)) }
                 : d);
         },
@@ -313,24 +340,24 @@ function useCreatePost() {
 function useCreateComment() {
     const cfg = (0, provider_1.useCommunityConfig)();
     const queryClient = (0, react_query_1.useQueryClient)();
+    const locale = (0, locale_1.readerLocale)(cfg);
     return (0, react_query_1.useMutation)({
         onMutate: async ({ postId, text, authorName }) => {
-            await queryClient.cancelQueries({ queryKey: threadKey(postId) });
-            await queryClient.cancelQueries({ queryKey: FEED_KEY });
+            await queryClient.cancelQueries({ queryKey: (0, keys_1.threadKey)(postId, locale) });
+            await queryClient.cancelQueries({ queryKey: keys_1.FEED_KEY });
             const tempId = `optimistic-${Date.now()}`;
             const optimistic = {
                 id: tempId,
                 postId,
-                authorId: "",
                 authorName,
                 authorOfficial: false,
-                authorHandle: null,
-                authorAvatarUrl: null,
+                ...ownAuthorFields(queryClient),
                 text,
                 isOwn: true,
                 createdAt: new Date().toISOString(),
+                translation: null,
             };
-            queryClient.setQueryData(threadKey(postId), (d) => [
+            queryClient.setQueryData((0, keys_1.threadKey)(postId, locale), (d) => [
                 ...(d ?? []),
                 optimistic,
             ]);
@@ -344,7 +371,7 @@ function useCreateComment() {
         },
         onSuccess: ({ id, verdict }, { postId, text }, { tempId }) => {
             const rejected = verdict.status === "rejected";
-            queryClient.setQueryData(threadKey(postId), (d) => (d ?? [])
+            queryClient.setQueryData((0, keys_1.threadKey)(postId, locale), (d) => (d ?? [])
                 .filter((c) => !(rejected && c.id === tempId))
                 .map((c) => (c.id === tempId ? { ...c, id } : c)));
             // A rejected comment never becomes visible, so undo the optimistic bump.
@@ -359,7 +386,7 @@ function useCreateComment() {
             }
         },
         onError: (_e, { postId }, context) => {
-            queryClient.setQueryData(threadKey(postId), (d) => (d ?? []).filter((c) => c.id !== context?.tempId));
+            queryClient.setQueryData((0, keys_1.threadKey)(postId, locale), (d) => (d ?? []).filter((c) => c.id !== context?.tempId));
             bumpFeedCommentCount(queryClient, postId, -1);
         },
     });
@@ -473,14 +500,15 @@ function useBlockUser() {
 function useDeleteContent() {
     const cfg = (0, provider_1.useCommunityConfig)();
     const queryClient = (0, react_query_1.useQueryClient)();
+    const locale = (0, locale_1.readerLocale)(cfg);
     return (0, react_query_1.useMutation)({
         mutationFn: ({ kind, id }) => kind === "post" ? (0, service_1.deleteOwnPost)(cfg, id) : (0, service_1.deleteOwnComment)(cfg, id),
         onSuccess: (_data, { kind, postId }) => {
             (0, events_1.emitEvent)(cfg, events_1.COMMUNITY_EVENTS.contentDeleted, { contentType: kind });
-            queryClient.invalidateQueries({ queryKey: threadKey(postId) });
-            queryClient.invalidateQueries({ queryKey: FEED_KEY });
-            queryClient.invalidateQueries({ queryKey: USER_POSTS_KEY });
-            queryClient.invalidateQueries({ queryKey: SEARCH_KEY });
+            queryClient.invalidateQueries({ queryKey: (0, keys_1.threadKey)(postId, locale) });
+            queryClient.invalidateQueries({ queryKey: keys_1.FEED_KEY });
+            queryClient.invalidateQueries({ queryKey: keys_1.USER_POSTS_KEY });
+            queryClient.invalidateQueries({ queryKey: keys_1.SEARCH_KEY });
         },
     });
 }

package/lib/inbox-service.d.ts

@@ -12,6 +12,11 @@ export interface InboxState {
     /** Everything at or before this instant is read; null = never opened. */
     seenAt: string | null;
 }
+/** Same truncation as list_notifications()'s `left(p.content, 140)`. */
+export declare function localizeExcerpts(items: InboxItem[], translations: {
+    post_id: string;
+    content: string;
+}[]): InboxItem[];
 /** The inbox's whole state in one fetch: items (newest first) + seen marker. */
 export declare function fetchInbox(cfg: ResolvedCommunityConfig): Promise<InboxState>;
 /**

package/lib/inbox-service.js

@@ -12,11 +12,25 @@
 // support-reply kind) passes through untouched instead of being special-cased
 // here — the host UI decides what to do with a kind it doesn't recognize.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.localizeExcerpts = localizeExcerpts;
 exports.fetchInbox = fetchInbox;
 exports.markInboxSeen = markInboxSeen;
 exports.unreadCount = unreadCount;
 const identity_1 = require("./identity");
+const locale_1 = require("./locale");
 const INBOX_PAGE_SIZE = 50;
+/** Same truncation as list_notifications()'s `left(p.content, 140)`. */
+function localizeExcerpts(items, translations) {
+    if (translations.length === 0)
+        return items;
+    const byPost = new Map(translations.map((t) => [t.post_id, t.content.slice(0, 140)]));
+    return items.map((item) => {
+        const translated = item.postId ? byPost.get(item.postId) : undefined;
+        return translated === undefined
+            ? item
+            : { ...item, payload: { ...item.payload, postExcerpt: translated } };
+    });
+}
 async function requireUid(cfg) {
     const uid = await (0, identity_1.ensureIdentity)(cfg);
     if (!uid)
@@ -61,7 +75,23 @@ async function fetchInbox(cfg) {
     if (seenRes.error)
         throw seenRes.error;
     const items = (listRes.data ?? []).map(mapNotificationRow);
-    return { items, seenAt: seenRes.data?.seen_at ?? null };
+    const locale = (0, locale_1.readerLocale)(cfg);
+    const postIds = [
+        ...new Set(items.map((i) => i.postId).filter((id) => Boolean(id))),
+    ];
+    let localized = items;
+    if (locale && postIds.length > 0) {
+        const { data, error } = await client
+            .from("post_translations")
+            .select("post_id, content")
+            .eq("locale", locale)
+            .in("post_id", postIds);
+        if (error) {
+            console.warn("[@rocapine/community-core] inbox translations unavailable, showing original excerpts:", error.message);
+        }
+        localized = localizeExcerpts(items, (data ?? []));
+    }
+    return { items: localized, seenAt: seenRes.data?.seen_at ?? null };
 }
 /**
  * Marks everything currently in the inbox as read. The brief's signature

package/lib/index.d.ts

@@ -1,7 +1,8 @@
 export type { CommunityTopicDef, CommunityModules, CommunityHostAdapters, CommunityFeedConfig, CommunityConfig, ResolvedCommunityConfig, } from "./config";
 export { CommunityDisabledError, resolveConfig } from "./config";
+export { readerLocale, languageOf } from "./locale";
 export { CommunityProvider, useCommunityConfig } from "./provider";
-export type { PostRow, PollOptionRow, CommentRow, ProfileRow, PollOption, FeedPoll, PollData, ReactionData, FeedPost, ThreadComment, CommunityProfile, } from "./models";
+export type { PostRow, PollOptionRow, CommentRow, ProfileRow, PollOption, FeedPoll, PollData, ReactionData, FeedPost, ThreadComment, CommunityProfile, TranslationInfo, TranslationRowEmbed, } from "./models";
 export { FEED_PAGE_SIZE, POST_MAX_LENGTH, COMMENT_MAX_LENGTH, POLL_MIN_OPTIONS, POLL_MAX_OPTIONS, POLL_OPTION_MAX_LENGTH, EMPTY_POLL_DATA, EMPTY_REACTION_DATA, displayName, normalizeTopic, mapProfileRow, buildPoll, pollPercent, mapPostRow, applyPollVote, applyReaction, mapCommentRow, newPostsLabel, newestCreatedAt, } from "./models";
 export type { TimeAgoParts } from "./time";
 export { timeAgo, timeAgoParts } from "./time";
@@ -10,8 +11,8 @@ export type { CommunityEventName } from "./events";
 export { ensureIdentity, resetIdentity, syncProfileFromHost } from "./identity";
 export { buildFeedSelect, fetchFeedPage, countNewPosts, fetchProfile, fetchUserPosts, searchPosts, fetchThread, createPost, votePoll, createComment, moderateOne, setLike, setReaction, fetchReactionSummaries, reportContent, blockUser, deleteOwnPost, deleteOwnComment, updateProfile, uploadAvatar, } from "./service";
 export type { ModerationVerdict, CreatePostInput, ReportReason, ReportInput, UpdateProfileInput, UpdateProfileResult, } from "./service";
-export { useCommunityFeed, useSearchPosts, useNewPostsCount, useCommunityUnseenCount, useThread, useProfile, useUserPosts, useMyUid, useUpdateProfile, useCreatePost, useCreateComment, useToggleLike, useVotePoll, useReactToPost, useReport, useBlockUser, useDeleteContent, } from "./hooks";
-export { fetchInbox, markInboxSeen, unreadCount } from "./inbox-service";
+export { useCommunityFeed, useSearchPosts, useNewPostsCount, useCommunityUnseenCount, useThread, useProfile, useUserPosts, useMyUid, useUpdateProfile, useCreatePost, useCreateComment, useToggleLike, useVotePoll, useReactToPost, useReport, useBlockUser, useDeleteContent, isOptimistic, } from "./hooks";
+export { fetchInbox, localizeExcerpts, markInboxSeen, unreadCount } from "./inbox-service";
 export type { InboxItem, InboxState } from "./inbox-service";
 export { useNotificationInbox, useUnreadNotificationCount, useMarkInboxSeen } from "./inbox-hooks";
 export { REQUIRED_SCHEMA_VERSION } from "./schema-check";

package/lib/index.js

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.uploadAvatar = exports.updateProfile = exports.deleteOwnComment = exports.deleteOwnPost = exports.blockUser = exports.reportContent = exports.fetchReactionSummaries = exports.setReaction = exports.setLike = exports.moderateOne = exports.createComment = exports.votePoll = exports.createPost = exports.fetchThread = exports.searchPosts = exports.fetchUserPosts = exports.fetchProfile = exports.countNewPosts = exports.fetchFeedPage = exports.buildFeedSelect = exports.syncProfileFromHost = exports.resetIdentity = exports.ensureIdentity = exports.emitEvent = exports.COMMUNITY_EVENTS = exports.timeAgoParts = exports.timeAgo = exports.newestCreatedAt = exports.newPostsLabel = exports.mapCommentRow = exports.applyReaction = exports.applyPollVote = exports.mapPostRow = exports.pollPercent = exports.buildPoll = exports.mapProfileRow = exports.normalizeTopic = exports.displayName = exports.EMPTY_REACTION_DATA = exports.EMPTY_POLL_DATA = exports.POLL_OPTION_MAX_LENGTH = exports.POLL_MAX_OPTIONS = exports.POLL_MIN_OPTIONS = exports.COMMENT_MAX_LENGTH = exports.POST_MAX_LENGTH = exports.FEED_PAGE_SIZE = exports.useCommunityConfig = exports.CommunityProvider = exports.resolveConfig = exports.CommunityDisabledError = void 0;
-exports.REQUIRED_SCHEMA_VERSION = exports.useMarkInboxSeen = exports.useUnreadNotificationCount = exports.useNotificationInbox = exports.unreadCount = exports.markInboxSeen = exports.fetchInbox = exports.useDeleteContent = exports.useBlockUser = exports.useReport = exports.useReactToPost = exports.useVotePoll = exports.useToggleLike = exports.useCreateComment = exports.useCreatePost = exports.useUpdateProfile = exports.useMyUid = exports.useUserPosts = exports.useProfile = exports.useThread = exports.useCommunityUnseenCount = exports.useNewPostsCount = exports.useSearchPosts = exports.useCommunityFeed = void 0;
+exports.deleteOwnComment = exports.deleteOwnPost = exports.blockUser = exports.reportContent = exports.fetchReactionSummaries = exports.setReaction = exports.setLike = exports.moderateOne = exports.createComment = exports.votePoll = exports.createPost = exports.fetchThread = exports.searchPosts = exports.fetchUserPosts = exports.fetchProfile = exports.countNewPosts = exports.fetchFeedPage = exports.buildFeedSelect = exports.syncProfileFromHost = exports.resetIdentity = exports.ensureIdentity = exports.emitEvent = exports.COMMUNITY_EVENTS = exports.timeAgoParts = exports.timeAgo = exports.newestCreatedAt = exports.newPostsLabel = exports.mapCommentRow = exports.applyReaction = exports.applyPollVote = exports.mapPostRow = exports.pollPercent = exports.buildPoll = exports.mapProfileRow = exports.normalizeTopic = exports.displayName = exports.EMPTY_REACTION_DATA = exports.EMPTY_POLL_DATA = exports.POLL_OPTION_MAX_LENGTH = exports.POLL_MAX_OPTIONS = exports.POLL_MIN_OPTIONS = exports.COMMENT_MAX_LENGTH = exports.POST_MAX_LENGTH = exports.FEED_PAGE_SIZE = exports.useCommunityConfig = exports.CommunityProvider = exports.languageOf = exports.readerLocale = exports.resolveConfig = exports.CommunityDisabledError = void 0;
+exports.REQUIRED_SCHEMA_VERSION = exports.useMarkInboxSeen = exports.useUnreadNotificationCount = exports.useNotificationInbox = exports.unreadCount = exports.markInboxSeen = exports.localizeExcerpts = exports.fetchInbox = exports.isOptimistic = exports.useDeleteContent = exports.useBlockUser = exports.useReport = exports.useReactToPost = exports.useVotePoll = exports.useToggleLike = exports.useCreateComment = exports.useCreatePost = exports.useUpdateProfile = exports.useMyUid = exports.useUserPosts = exports.useProfile = exports.useThread = exports.useCommunityUnseenCount = exports.useNewPostsCount = exports.useSearchPosts = exports.useCommunityFeed = exports.uploadAvatar = exports.updateProfile = void 0;
 var config_1 = require("./config");
 Object.defineProperty(exports, "CommunityDisabledError", { enumerable: true, get: function () { return config_1.CommunityDisabledError; } });
 Object.defineProperty(exports, "resolveConfig", { enumerable: true, get: function () { return config_1.resolveConfig; } });
+var locale_1 = require("./locale");
+Object.defineProperty(exports, "readerLocale", { enumerable: true, get: function () { return locale_1.readerLocale; } });
+Object.defineProperty(exports, "languageOf", { enumerable: true, get: function () { return locale_1.languageOf; } });
 var provider_1 = require("./provider");
 Object.defineProperty(exports, "CommunityProvider", { enumerable: true, get: function () { return provider_1.CommunityProvider; } });
 Object.defineProperty(exports, "useCommunityConfig", { enumerable: true, get: function () { return provider_1.useCommunityConfig; } });
@@ -77,8 +80,10 @@ Object.defineProperty(exports, "useReactToPost", { enumerable: true, get: functi
 Object.defineProperty(exports, "useReport", { enumerable: true, get: function () { return hooks_1.useReport; } });
 Object.defineProperty(exports, "useBlockUser", { enumerable: true, get: function () { return hooks_1.useBlockUser; } });
 Object.defineProperty(exports, "useDeleteContent", { enumerable: true, get: function () { return hooks_1.useDeleteContent; } });
+Object.defineProperty(exports, "isOptimistic", { enumerable: true, get: function () { return hooks_1.isOptimistic; } });
 var inbox_service_1 = require("./inbox-service");
 Object.defineProperty(exports, "fetchInbox", { enumerable: true, get: function () { return inbox_service_1.fetchInbox; } });
+Object.defineProperty(exports, "localizeExcerpts", { enumerable: true, get: function () { return inbox_service_1.localizeExcerpts; } });
 Object.defineProperty(exports, "markInboxSeen", { enumerable: true, get: function () { return inbox_service_1.markInboxSeen; } });
 Object.defineProperty(exports, "unreadCount", { enumerable: true, get: function () { return inbox_service_1.unreadCount; } });
 var inbox_hooks_1 = require("./inbox-hooks");

package/lib/keys.d.ts

@@ -0,0 +1,7 @@
+export declare const FEED_KEY: readonly ["community", "feed"];
+export declare const feedKey: (topic?: string, locale?: string | null) => readonly ["community", "feed", string, string];
+export declare const threadKey: (postId: string, locale?: string | null) => readonly ["community", "thread", string, string];
+export declare const USER_POSTS_KEY: readonly ["community", "userPosts"];
+export declare const userPostsKey: (userId: string, locale?: string | null) => readonly ["community", "userPosts", string, string];
+export declare const SEARCH_KEY: readonly ["community", "search"];
+export declare const searchKey: (cleaned: string, locale?: string | null) => readonly ["community", "search", string, string];

package/lib/keys.js

@@ -0,0 +1,18 @@
+"use strict";
+// React Query keys (internal, not exported from the package). Every full key
+// ends with the reader locale ("src" = originals) so switching locale never
+// serves another locale's cached translations; the *_KEY prefixes stay
+// prefixes of the full keys so setQueriesData/invalidateQueries match them all.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchKey = exports.SEARCH_KEY = exports.userPostsKey = exports.USER_POSTS_KEY = exports.threadKey = exports.feedKey = exports.FEED_KEY = void 0;
+exports.FEED_KEY = ["community", "feed"];
+const feedKey = (topic, locale) => [...exports.FEED_KEY, topic ?? "all", locale ?? "src"];
+exports.feedKey = feedKey;
+const threadKey = (postId, locale) => ["community", "thread", postId, locale ?? "src"];
+exports.threadKey = threadKey;
+exports.USER_POSTS_KEY = ["community", "userPosts"];
+const userPostsKey = (userId, locale) => [...exports.USER_POSTS_KEY, userId, locale ?? "src"];
+exports.userPostsKey = userPostsKey;
+exports.SEARCH_KEY = ["community", "search"];
+const searchKey = (cleaned, locale) => [...exports.SEARCH_KEY, cleaned, locale ?? "src"];
+exports.searchKey = searchKey;

package/lib/locale.d.ts

@@ -0,0 +1,8 @@
+import type { ResolvedCommunityConfig } from "./config";
+export declare function languageOf(locale: string): string;
+/**
+ * The locale translations are read in: the host's locale resolved against
+ * `modules.translation.locales` — exact match, else the first declared locale
+ * of the same language, else null (originals only). Null when the module is off.
+ */
+export declare function readerLocale(cfg: ResolvedCommunityConfig): string | null;

package/lib/locale.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.languageOf = languageOf;
+exports.readerLocale = readerLocale;
+function languageOf(locale) {
+    return locale.split("-")[0]?.toLowerCase() ?? "";
+}
+/**
+ * The locale translations are read in: the host's locale resolved against
+ * `modules.translation.locales` — exact match, else the first declared locale
+ * of the same language, else null (originals only). Null when the module is off.
+ */
+function readerLocale(cfg) {
+    const module = cfg.modules.translation;
+    if (!module || module.locales.length === 0)
+        return null;
+    const host = cfg.host.getLocale();
+    if (module.locales.includes(host))
+        return host;
+    const lang = languageOf(host);
+    return module.locales.find((l) => languageOf(l) === lang) ?? null;
+}

package/lib/models.d.ts

@@ -29,11 +29,29 @@ export interface PostRow {
     /** Empty for a post without a poll; absent entirely when the polls module
      * is off (the embed is then not part of the select). */
     poll_options?: PollOptionRow[];
+    /** At most one row: server-filtered to the reader's locale. Absent when the
+     * translation module is off. */
+    post_translations?: TranslationRowEmbed[];
 }
 export interface PollOptionRow {
     id: string;
     idx: number;
     label: string;
+    /** At most one row: server-filtered to the reader's locale. */
+    poll_option_translations?: {
+        content: string;
+    }[];
+}
+/** One embedded translation row, filtered server-side on the reader locale. */
+export interface TranslationRowEmbed {
+    locale: string;
+    source_locale: string;
+    content: string;
+}
+export interface TranslationInfo {
+    text: string;
+    /** Detected language of the original (short code: en, es, pt…). */
+    sourceLocale: string;
 }
 export interface CommentRow {
     id: string;
@@ -48,10 +66,15 @@ export interface CommentRow {
         handle: string | null;
         avatar_url: string | null;
     } | null;
+    /** At most one row: server-filtered to the reader's locale. Absent when the
+     * translation module is off. */
+    comment_translations?: TranslationRowEmbed[];
 }
 export interface PollOption {
     id: string;
     label: string;
+    /** Label in the reader locale when the translation module provided one. */
+    translatedLabel: string | null;
     votes: number;
 }
 export interface FeedPoll {
@@ -107,6 +130,9 @@ export interface FeedPost {
     /** Display name of the most recent reactor, for a "X and N others reacted" affordance;
      * null when nobody has reacted yet or the reaction module is off. */
     lastReactorName: string | null;
+    /** Reader-locale translation; null when the item is already in the reader's language,
+     * not translated yet, or the module is off. `text` stays the original. */
+    translation: TranslationInfo | null;
 }
 export interface ThreadComment {
     id: string;
@@ -119,6 +145,9 @@ export interface ThreadComment {
     text: string;
     isOwn: boolean;
     createdAt: string;
+    /** Reader-locale translation; null when the item is already in the reader's language,
+     * not translated yet, or the module is off. `text` stays the original. */
+    translation: TranslationInfo | null;
 }
 /**
  * Public display name, with a host-configured fallback for profiles not yet named.

package/lib/models.js

@@ -65,13 +65,22 @@ function mapProfileRow(row, fallback) {
         username: row.username ?? null,
     };
 }
+function embedToTranslation(rows) {
+    const row = rows?.[0];
+    return row ? { text: row.content, sourceLocale: row.source_locale } : null;
+}
 /** Assemble a FeedPoll from the embedded option rows + batched vote data. */
 function buildPoll(options, counts, myOptionId) {
     if (!options || options.length === 0)
         return null;
     const mapped = [...options]
         .sort((a, b) => a.idx - b.idx)
-        .map((o) => ({ id: o.id, label: o.label, votes: counts.get(o.id) ?? 0 }));
+        .map((o) => ({
+        id: o.id,
+        label: o.label,
+        translatedLabel: o.poll_option_translations?.[0]?.content ?? null,
+        votes: counts.get(o.id) ?? 0,
+    }));
     return {
         options: mapped,
         myOptionId,
@@ -108,6 +117,7 @@ transformPost) {
         reactionCount: reactionData.counts.get(row.id) ?? 0,
         hasReacted: reactionData.mine.has(row.id),
         lastReactorName: reactionData.lastReactorName.get(row.id) ?? null,
+        translation: embedToTranslation(row.post_translations),
     };
     return transformPost ? transformPost(post, row) : post;
 }
@@ -157,6 +167,7 @@ function mapCommentRow(row, myUid, fallback) {
         text: row.content,
         isOwn: row.author_id === myUid,
         createdAt: row.created_at,
+        translation: embedToTranslation(row.comment_translations),
     };
 }
 /** Floating pill label. "1 new post" / "N new posts". */

package/lib/service.d.ts

@@ -5,7 +5,16 @@ import { type CommunityProfile, type FeedPost, type ReactionData, type ThreadCom
  * exported so it's unit-testable without a Supabase client. Invalid column
  * names are dropped with a `console.warn` rather than failing the query.
  */
-export declare function buildFeedSelect(extraPostColumns?: readonly string[], polls?: boolean): string;
+export declare function buildFeedSelect(extraPostColumns?: readonly string[], polls?: boolean, translations?: boolean): string;
+/** Embedded-resource filters: keep only the reader locale's translation rows,
+ * so `rows?.[0]` in the mappers is always that locale, never some other
+ * locale's leftover row. PostgREST accepts dotted paths for nested embeds,
+ * the same mechanism as the existing `.eq("comments.status", "visible")`. A
+ * no-op (module off / no resolved locale) leaves the query, and therefore
+ * every byte of it, unchanged from before translations existed. */
+export declare function withTranslationFilters<Q extends {
+    eq(column: string, value: string): Q;
+}>(query: Q, cfg: ResolvedCommunityConfig): Q;
 /**
  * Batched reaction state for one page: count + last reactor's display name + my-reaction
  * flag, all from the single security-definer `post_reaction_summary` RPC (the backend
@@ -46,9 +55,12 @@ export declare function fetchUserPosts(cfg: ResolvedCommunityConfig, userId: str
  * page-index cursor as `fetchFeedPage` (product decision, reversing the
  * earlier single-page scope cut).
  */
-export declare function searchPosts(cfg: ResolvedCommunityConfig, query: string, opts?: {
+export declare function searchPosts(cfg: ResolvedCommunityConfig, searchTerm: string, opts?: {
     cursor?: number;
 }): Promise<FeedPost[]>;
+/** The thread (comments) select: + the translation embed iff the reader has a
+ * resolved translation locale. */
+export declare function threadSelect(cfg: ResolvedCommunityConfig): string;
 /**
  * Note: `cfg.feed.extraPostColumns`/`transformPost` do NOT apply here — this
  * queries `comments`, not `posts` (the thread's parent post is passed in by

package/lib/service.js

@@ -9,12 +9,14 @@
 // generalized from that host's prayer-style feature's summary RPC into `post_reaction_summary`).
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildFeedSelect = buildFeedSelect;
+exports.withTranslationFilters = withTranslationFilters;
 exports.fetchReactionSummaries = fetchReactionSummaries;
 exports.fetchFeedPage = fetchFeedPage;
 exports.countNewPosts = countNewPosts;
 exports.fetchProfile = fetchProfile;
 exports.fetchUserPosts = fetchUserPosts;
 exports.searchPosts = searchPosts;
+exports.threadSelect = threadSelect;
 exports.fetchThread = fetchThread;
 exports.createPost = createPost;
 exports.votePoll = votePoll;
@@ -30,6 +32,7 @@ exports.updateProfile = updateProfile;
 exports.uploadAvatar = uploadAvatar;
 const supabase_js_1 = require("@supabase/supabase-js");
 const identity_1 = require("./identity");
+const locale_1 = require("./locale");
 const models_1 = require("./models");
 /** Avatar images live in this Storage bucket on every install (mold value, unchanged). */
 const AVATAR_BUCKET = "avatars";
@@ -46,6 +49,14 @@ const FEED_SELECT = "id, author_id, topic, content, status, pinned_at, created_a
  * `poll_options` table does not exist and PostgREST rejects the whole select
  * (PGRST200), which took the entire feed down for such installs. */
 const POLL_OPTIONS_SELECT = "poll_options(id, idx, label)";
+/** Same embed, plus each option's translation row — used when the reader has
+ * a resolved translation locale (see `readerLocale`). */
+const POLL_OPTIONS_TRANSLATED_SELECT = "poll_options(id, idx, label, poll_option_translations(content))";
+/** Embedded only when the reader has a resolved translation locale. */
+const POST_TRANSLATIONS_SELECT = "post_translations(locale, source_locale, content)";
+const COMMENTS_SELECT = "id, post_id, author_id, content, status, created_at, profiles(username, is_official, handle, avatar_url)";
+/** Embedded only when the reader has a resolved translation locale. */
+const COMMENT_TRANSLATIONS_SELECT = "comment_translations(locale, source_locale, content)";
 const PROFILE_SELECT = "id, username, handle, is_official, bio, avatar_url";
 /** Minimal injection guard for `CommunityConfig.feed.extraPostColumns`: a bare
  * column name only, no `.`, `(`, `:`, whitespace, etc. — those are how a
@@ -58,8 +69,13 @@ const VALID_EXTRA_COLUMN = /^[a-z0-9_]+$/;
  * exported so it's unit-testable without a Supabase client. Invalid column
  * names are dropped with a `console.warn` rather than failing the query.
  */
-function buildFeedSelect(extraPostColumns, polls = false) {
-    const base = polls ? `${FEED_SELECT}, ${POLL_OPTIONS_SELECT}` : FEED_SELECT;
+function buildFeedSelect(extraPostColumns, polls = false, translations = false) {
+    const parts = [FEED_SELECT];
+    if (polls)
+        parts.push(translations ? POLL_OPTIONS_TRANSLATED_SELECT : POLL_OPTIONS_SELECT);
+    if (translations)
+        parts.push(POST_TRANSLATIONS_SELECT);
+    const base = parts.join(", ");
     if (!extraPostColumns || extraPostColumns.length === 0)
         return base;
     const valid = extraPostColumns.filter((column) => {
@@ -73,9 +89,25 @@ function buildFeedSelect(extraPostColumns, polls = false) {
     return `${base}, ${valid.join(", ")}`;
 }
 /** The posts select for this install: `feed.extraPostColumns` + the poll
- * embed iff `modules.polls`. */
+ * embed iff `modules.polls`, + translation embeds iff the reader has a
+ * resolved translation locale. */
 function postsSelect(cfg) {
-    return buildFeedSelect(cfg.feed.extraPostColumns, cfg.modules.polls);
+    return buildFeedSelect(cfg.feed.extraPostColumns, cfg.modules.polls, (0, locale_1.readerLocale)(cfg) !== null);
+}
+/** Embedded-resource filters: keep only the reader locale's translation rows,
+ * so `rows?.[0]` in the mappers is always that locale, never some other
+ * locale's leftover row. PostgREST accepts dotted paths for nested embeds,
+ * the same mechanism as the existing `.eq("comments.status", "visible")`. A
+ * no-op (module off / no resolved locale) leaves the query, and therefore
+ * every byte of it, unchanged from before translations existed. */
+function withTranslationFilters(query, cfg) {
+    const locale = (0, locale_1.readerLocale)(cfg);
+    if (!locale)
+        return query;
+    let q = query.eq("post_translations.locale", locale);
+    if (cfg.modules.polls)
+        q = q.eq("poll_options.poll_option_translations.locale", locale);
+    return q;
 }
 async function fetchMyLikes(client, postIds, uid) {
     if (postIds.length === 0)
@@ -177,6 +209,7 @@ async function fetchFeedPage(cfg, opts = {}) {
         .order("pinned_at", { ascending: false, nullsFirst: false })
         .order("created_at", { ascending: false })
         .range(page * models_1.FEED_PAGE_SIZE, page * models_1.FEED_PAGE_SIZE + models_1.FEED_PAGE_SIZE - 1);
+    query = withTranslationFilters(query, cfg);
     if (opts.topic)
         query = query.eq("topic", opts.topic);
     const { data, error } = await query;
@@ -228,7 +261,7 @@ async function fetchUserPosts(cfg, userId, opts = {}) {
     const client = cfg.requireClient();
     const uid = await requireUid(cfg);
     const page = opts.cursor ?? 0;
-    const { data, error } = await client
+    let query = client
         .from("posts")
         .select(postsSelect(cfg))
         .eq("author_id", userId)
@@ -236,6 +269,8 @@ async function fetchUserPosts(cfg, userId, opts = {}) {
         .in("status", ["visible", "pending"])
         .order("created_at", { ascending: false })
         .range(page * models_1.FEED_PAGE_SIZE, page * models_1.FEED_PAGE_SIZE + models_1.FEED_PAGE_SIZE - 1);
+    query = withTranslationFilters(query, cfg);
+    const { data, error } = await query;
     if (error)
         throw error;
     return toFeedPosts(cfg, client, (data ?? []), uid);
@@ -245,14 +280,14 @@ async function fetchUserPosts(cfg, userId, opts = {}) {
  * page-index cursor as `fetchFeedPage` (product decision, reversing the
  * earlier single-page scope cut).
  */
-async function searchPosts(cfg, query, opts = {}) {
-    const cleaned = query.trim();
+async function searchPosts(cfg, searchTerm, opts = {}) {
+    const cleaned = searchTerm.trim();
     if (cleaned.length === 0)
         return [];
     const client = cfg.requireClient();
     const uid = await requireUid(cfg);
     const page = opts.cursor ?? 0;
-    const { data, error } = await client
+    let query = client
         .from("posts")
         .select(postsSelect(cfg))
         .eq("comments.status", "visible")
@@ -260,10 +295,17 @@ async function searchPosts(cfg, query, opts = {}) {
         .ilike("content", `%${cleaned}%`)
         .order("created_at", { ascending: false })
         .range(page * models_1.FEED_PAGE_SIZE, page * models_1.FEED_PAGE_SIZE + models_1.FEED_PAGE_SIZE - 1);
+    query = withTranslationFilters(query, cfg);
+    const { data, error } = await query;
     if (error)
         throw error;
     return toFeedPosts(cfg, client, (data ?? []), uid);
 }
+/** The thread (comments) select: + the translation embed iff the reader has a
+ * resolved translation locale. */
+function threadSelect(cfg) {
+    return (0, locale_1.readerLocale)(cfg) ? `${COMMENTS_SELECT}, ${COMMENT_TRANSLATIONS_SELECT}` : COMMENTS_SELECT;
+}
 /**
  * Note: `cfg.feed.extraPostColumns`/`transformPost` do NOT apply here — this
  * queries `comments`, not `posts` (the thread's parent post is passed in by
@@ -273,12 +315,16 @@ async function searchPosts(cfg, query, opts = {}) {
 async function fetchThread(cfg, postId) {
     const client = cfg.requireClient();
     const uid = await requireUid(cfg);
-    const { data, error } = await client
+    const locale = (0, locale_1.readerLocale)(cfg);
+    let query = client
         .from("comments")
-        .select("id, post_id, author_id, content, status, created_at, profiles(username, is_official, handle, avatar_url)")
+        .select(threadSelect(cfg))
         .eq("post_id", postId)
         .in("status", ["visible", "pending"])
         .order("created_at", { ascending: true });
+    if (locale)
+        query = query.eq("comment_translations.locale", locale);
+    const { data, error } = await query;
     if (error)
         throw error;
     return (data ?? []).map((r) => (0, models_1.mapCommentRow)(r, uid, cfg.anonymousAuthorFallback));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rocapine/community-core",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Headless Supabase-backed community backend: identity, feed/thread/moderation services, and React Query hooks.",
   "license": "MIT",
   "repository": {