@rocapine/community-core 0.1.0 → 0.3.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.
@@ -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,9 +177,10 @@ 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`.
-- **`timeAgo(iso)`** — hardcoded-English relative-time formatting, kept for
+  `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
   (see `formatTimeAgo` in `@rocapine/community-ui`).

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

@@ -76,14 +76,14 @@ export declare function useCreateComment(): import("@tanstack/react-query").UseM
 }, {
     tempId: string;
 }>;
-/** Optimistic like toggle across all cached feed pages (every topic filter). */
+/** Optimistic like toggle across every post cache (feed pages of every topic
+ * filter, user-posts and search — same sweep as votes/reactions, so a like
+ * from a profile or search screen is reflected immediately too). */
 export declare function useToggleLike(): import("@tanstack/react-query").UseMutationResult<void, Error, {
     postId: string;
     liked: boolean;
     topic: string | null;
-}, {
-    previous: [readonly unknown[], InfiniteData<FeedPost[], unknown> | undefined][];
-}>;
+}, PostCacheSnapshot>;
 /**
  * Optimistic poll vote across every post cache (mirror of useToggleLike, but
  * reaching the user-posts/search caches too — see `applyOptimisticToAllPostCaches`).

package/lib/hooks.js

@@ -30,15 +30,16 @@ exports.useDeleteContent = useDeleteContent;
 const react_query_1 = require("@tanstack/react-query");
 const events_1 = require("./events");
 const identity_1 = require("./identity");
+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 feedKey = (topic, locale) => [...FEED_KEY, topic ?? "all", locale ?? "src"];
+const threadKey = (postId, locale) => ["community", "thread", postId, locale ?? "src"];
 const profileKey = (userId) => ["community", "profile", userId];
-const userPostsKey = (userId) => ["community", "userPosts", userId];
 const USER_POSTS_KEY = ["community", "userPosts"];
+const userPostsKey = (userId, locale) => [...USER_POSTS_KEY, userId, locale ?? "src"];
 const SEARCH_KEY = ["community", "search"];
 /**
  * Adjust a post's commentCount across every cached feed page (all topic
@@ -94,8 +95,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: 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 +113,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: [...SEARCH_KEY, cleaned, locale ?? "src"],
         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 +166,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: threadKey(postId ?? "none", locale),
         queryFn: () => (0, service_1.fetchThread)(cfg, postId),
         enabled: cfg.supabase !== null && !!postId,
         staleTime: 1000 * 15,
@@ -186,8 +190,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: 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,
@@ -235,6 +240,7 @@ 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 });
@@ -259,7 +265,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 +278,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(feedKey(undefined, locale));
+            prepend(feedKey(topic, locale));
             return { tempId };
         },
         mutationFn: async ({ topic, text, pollOptions }) => {
@@ -313,9 +325,10 @@ 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: threadKey(postId, locale) });
             await queryClient.cancelQueries({ queryKey: FEED_KEY });
             const tempId = `optimistic-${Date.now()}`;
             const optimistic = {
@@ -329,8 +342,9 @@ function useCreateComment() {
                 text,
                 isOwn: true,
                 createdAt: new Date().toISOString(),
+                translation: null,
             };
-            queryClient.setQueryData(threadKey(postId), (d) => [
+            queryClient.setQueryData(threadKey(postId, locale), (d) => [
                 ...(d ?? []),
                 optimistic,
             ]);
@@ -344,7 +358,7 @@ function useCreateComment() {
         },
         onSuccess: ({ id, verdict }, { postId, text }, { tempId }) => {
             const rejected = verdict.status === "rejected";
-            queryClient.setQueryData(threadKey(postId), (d) => (d ?? [])
+            queryClient.setQueryData(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,39 +373,29 @@ function useCreateComment() {
             }
         },
         onError: (_e, { postId }, context) => {
-            queryClient.setQueryData(threadKey(postId), (d) => (d ?? []).filter((c) => c.id !== context?.tempId));
+            queryClient.setQueryData(threadKey(postId, locale), (d) => (d ?? []).filter((c) => c.id !== context?.tempId));
             bumpFeedCommentCount(queryClient, postId, -1);
         },
     });
 }
-/** Optimistic like toggle across all cached feed pages (every topic filter). */
+/** Optimistic like toggle across every post cache (feed pages of every topic
+ * filter, user-posts and search — same sweep as votes/reactions, so a like
+ * from a profile or search screen is reflected immediately too). */
 function useToggleLike() {
     const cfg = (0, provider_1.useCommunityConfig)();
     const queryClient = (0, react_query_1.useQueryClient)();
     return (0, react_query_1.useMutation)({
         mutationFn: ({ postId, liked }) => (0, service_1.setLike)(cfg, postId, liked),
-        onMutate: async ({ postId, liked }) => {
-            await queryClient.cancelQueries({ queryKey: FEED_KEY });
-            const previous = queryClient.getQueriesData({
-                queryKey: FEED_KEY,
-            });
-            queryClient.setQueriesData({ queryKey: FEED_KEY }, (data) => data
-                ? {
-                    ...data,
-                    pages: data.pages.map((page) => page.map((post) => post.id === postId
-                        ? {
-                            ...post,
-                            likedByMe: liked,
-                            likeCount: Math.max(0, post.likeCount + (liked ? 1 : -1)),
-                        }
-                        : post)),
-                }
-                : data);
-            return { previous };
-        },
-        onError: (_err, _vars, context) => {
-            for (const [key, data] of context?.previous ?? [])
-                queryClient.setQueryData(key, data);
+        onMutate: ({ postId, liked }) => applyOptimisticToAllPostCaches(queryClient, (post) => post.id === postId
+            ? {
+                ...post,
+                likedByMe: liked,
+                likeCount: Math.max(0, post.likeCount + (liked ? 1 : -1)),
+            }
+            : post),
+        onError: (_err, _vars, snapshot) => {
+            if (snapshot)
+                rollbackPostCaches(queryClient, snapshot);
         },
         onSuccess: (_data, { liked, postId, topic }) => {
             if (liked)
@@ -483,12 +487,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: threadKey(postId, locale) });
             queryClient.invalidateQueries({ queryKey: FEED_KEY });
+            queryClient.invalidateQueries({ queryKey: USER_POSTS_KEY });
+            queryClient.invalidateQueries({ queryKey: 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";
@@ -11,7 +12,7 @@ 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 { 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.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; } });
@@ -79,6 +82,7 @@ Object.defineProperty(exports, "useBlockUser", { enumerable: true, get: function
 Object.defineProperty(exports, "useDeleteContent", { enumerable: true, get: function () { return hooks_1.useDeleteContent; } });
 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/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

@@ -26,13 +26,32 @@ export interface PostRow {
     comments: {
         count: number;
     }[];
-    /** Empty for a post without a poll. */
-    poll_options: PollOptionRow[];
+    /** 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;
@@ -47,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 {
@@ -106,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;
@@ -118,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.
@@ -154,7 +184,7 @@ export interface CommunityProfile {
 }
 export declare function mapProfileRow(row: ProfileRow, fallback: string): CommunityProfile;
 /** Assemble a FeedPoll from the embedded option rows + batched vote data. */
-export declare function buildPoll(options: PollOptionRow[], counts: ReadonlyMap<string, number>, myOptionId: string | null): FeedPoll | null;
+export declare function buildPoll(options: PollOptionRow[] | undefined, counts: ReadonlyMap<string, number>, myOptionId: string | null): FeedPoll | null;
 /** Integer percentage for a result bar; a zero-vote poll shows 0% everywhere. */
 export declare function pollPercent(votes: number, totalVotes: number): number;
 export declare function mapPostRow(row: PostRow, myUid: string, fallback: string, topics: readonly CommunityTopicDef[], likedPostIds: ReadonlySet<string>, pollData?: PollData, reactionData?: ReactionData, 

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.length === 0)
+    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,7 @@ 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[]): string;
+export declare function buildFeedSelect(extraPostColumns?: readonly string[], polls?: boolean, translations?: boolean): string;
 /**
  * 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,7 +46,7 @@ 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[]>;
 /**

package/lib/service.js

@@ -30,6 +30,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";
@@ -41,7 +42,19 @@ async function requireUid(cfg) {
 }
 // Embedded filter: comment counts only count visible comments, so the badge
 // on a card always matches what the opened thread renders.
-const FEED_SELECT = "id, author_id, topic, content, status, pinned_at, created_at, profiles!posts_author_id_fkey(username, is_official, handle, avatar_url), likes(count), comments(count), poll_options(id, idx, label)";
+const FEED_SELECT = "id, author_id, topic, content, status, pinned_at, created_at, profiles!posts_author_id_fkey(username, is_official, handle, avatar_url), likes(count), comments(count)";
+/** Embedded only when the polls module is on: on a core-only backend the
+ * `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
@@ -54,9 +67,15 @@ 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) {
+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 FEED_SELECT;
+        return base;
     const valid = extraPostColumns.filter((column) => {
         if (VALID_EXTRA_COLUMN.test(column))
             return true;
@@ -64,8 +83,29 @@ function buildFeedSelect(extraPostColumns) {
         return false;
     });
     if (valid.length === 0)
-        return FEED_SELECT;
-    return `${FEED_SELECT}, ${valid.join(", ")}`;
+        return base;
+    return `${base}, ${valid.join(", ")}`;
+}
+/** The posts select for this install: `feed.extraPostColumns` + the poll
+ * 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, (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)
@@ -143,7 +183,7 @@ async function toFeedPosts(cfg, client, rows, uid) {
     const postIds = rows.map((r) => r.id);
     const [liked, pollData, reactionData] = await Promise.all([
         fetchMyLikes(client, postIds, uid),
-        fetchPollData(cfg, rows.filter((r) => r.poll_options.length > 0).map((r) => r.id), uid),
+        fetchPollData(cfg, rows.filter((r) => (r.poll_options ?? []).length > 0).map((r) => r.id), uid),
         fetchReactionSummaries(cfg, postIds),
     ]);
     return rows.map((r) => (0, models_1.mapPostRow)(r, uid, cfg.anonymousAuthorFallback, cfg.topics, liked, pollData, reactionData, cfg.feed.transformPost));
@@ -158,7 +198,7 @@ async function fetchFeedPage(cfg, opts = {}) {
     const page = opts.cursor ?? 0;
     let query = client
         .from("posts")
-        .select(buildFeedSelect(cfg.feed.extraPostColumns))
+        .select(postsSelect(cfg))
         .eq("comments.status", "visible")
         // Others' rows are already limited to 'visible' by RLS; this also shows the
         // author their own 'pending' posts (optimistic) while hiding their moderated-out
@@ -167,6 +207,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;
@@ -218,14 +259,16 @@ 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(buildFeedSelect(cfg.feed.extraPostColumns))
+        .select(postsSelect(cfg))
         .eq("author_id", userId)
         .eq("comments.status", "visible")
         .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);
@@ -235,21 +278,23 @@ 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(buildFeedSelect(cfg.feed.extraPostColumns))
+        .select(postsSelect(cfg))
         .eq("comments.status", "visible")
         .eq("status", "visible")
         .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);
@@ -263,12 +308,17 @@ 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);
+    const select = locale ? `${COMMENTS_SELECT}, ${COMMENT_TRANSLATIONS_SELECT}` : COMMENTS_SELECT;
+    let query = client
         .from("comments")
-        .select("id, post_id, author_id, content, status, created_at, profiles(username, is_official, handle, avatar_url)")
+        .select(select)
         .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.1.0",
+  "version": "0.3.0",
   "description": "Headless Supabase-backed community backend: identity, feed/thread/moderation services, and React Query hooks.",
   "license": "MIT",
   "repository": {