hive-react-kit 0.9.2 → 0.9.4

package/README.md

@@ -10,6 +10,7 @@ A comprehensive React component library for building Hive blockchain application
 - 🎯 **TypeScript Support** - Full TypeScript support with type definitions
 - 🚀 **Tree Shaking** - Optimized bundle size with tree shaking support
 - 🎭 **Customizable** - Easy to customize and extend
+- 🌐 **Content i18n** - Wrap once, every Hive post body / comment / feed preview translates to the user's language. See [docs/i18n.md](docs/i18n.md)
 
 ## Installation
 
@@ -415,6 +416,45 @@ See [docs/HiveContributionsLanding.md](docs/HiveContributionsLanding.md) for ful
 | 3Speak | https://3speak.tv/ |
 | HiveFestFacts | https://hivefestfacts.sagarkothari88.one/ |
 
+### Content Translation (i18n)
+
+Wrap your app once with `<HiveLanguageProvider>` and every Hive content body / title / comment / feed preview rendered by the kit translates to the chosen language. Free MyMemory-backed translator by default, fully overridable for DeepL / Google / your own backend.
+
+```tsx
+import { HiveLanguageProvider } from 'hive-react-kit';
+
+<HiveLanguageProvider language="es">
+  <App />
+</HiveLanguageProvider>
+```
+
+**Auto-translates:** post bodies (`HiveDetailPost`, `InlineCommentItem`, `CommentTile`, `UserChannel`), feed-card titles + previews (`UserDetailProfile`), poll questions / previews / choice labels (`PollListItem`).
+
+**Available exports:**
+
+| Export | Purpose |
+|--------|---------|
+| `HiveLanguageProvider` | Wrap app once with `language="es"` (or any code MyMemory accepts). `language="en"` is no-op |
+| `useHiveLanguage()` | Read current `{ language, translateHtml }` from context |
+| `useTranslatedHtml(html)` | Hook returning `{ html, loading }` for translated rendered HTML |
+| `useTranslatedText(text)` | Hook returning `{ text, loading }` for translated plain strings |
+| `<TranslatedBody>` | `forwardRef`-aware drop-in for `<div … dangerouslySetInnerHTML>` |
+| `<TranslatedText>` | Inline wrapper for plain strings inside `.map()` loops |
+| `translateHtml`, `translateText` | Low-level helpers (rarely needed) |
+
+**Custom translator** — pass `translateHtml` to override the bundled MyMemory implementation:
+
+```tsx
+<HiveLanguageProvider
+  language={language}
+  translateHtml={async (html, target) => callDeepL(html, target)}
+>
+  <App />
+</HiveLanguageProvider>
+```
+
+See [docs/i18n.md](docs/i18n.md) for the full provider API, hook signatures, custom-translator integration, caching layers, failure modes, and behaviour with code blocks / embeds.
+
 ### Feed Components
 
 - **PostFeedList** - Display a list of posts with sorting, filtering, and interaction capabilities

package/dist/components/TranslatedBody.d.ts

@@ -0,0 +1,20 @@
+import React from "react";
+export interface TranslatedBodyProps {
+    /** Rendered post / comment body HTML (output of `createHiveRenderer`). */
+    html: string;
+    className?: string;
+    onClick?: React.MouseEventHandler<HTMLDivElement>;
+}
+/**
+ * Drop-in replacement for
+ *   `<div className="…" onClick={…} dangerouslySetInnerHTML={{ __html: html }} />`
+ * that translates the body into the language supplied by the nearest
+ * `<HiveLanguageProvider>`. Forwards refs to the inner div so existing
+ * click-delegation / image-fallback logic continues to attach correctly.
+ *
+ * While translation is in flight the original HTML is shown and the
+ * `data-translating="true"` attribute is set on the div so consumers
+ * can apply a CSS-only loading style if they want.
+ */
+export declare const TranslatedBody: React.ForwardRefExoticComponent<TranslatedBodyProps & React.RefAttributes<HTMLDivElement>>;
+export default TranslatedBody;

package/dist/components/TranslatedText.d.ts

@@ -0,0 +1,26 @@
+import React from "react";
+export interface TranslatedTextProps {
+    /** Plain-text source string (post title, snippet, caption, etc.). */
+    text: string | null | undefined;
+    /**
+     * Optional fallback rendered when both translated and source text are
+     * empty — typically the calling component already conditionally renders
+     * this wrapper, so it's rarely needed.
+     */
+    fallback?: React.ReactNode;
+}
+/**
+ * Drop-in inline wrapper for translating a plain string into the language
+ * supplied by the nearest `<HiveLanguageProvider>`. Useful inside loops /
+ * `.map()` render functions where calling `useTranslatedText` directly
+ * would break the rules of hooks.
+ *
+ * ```tsx
+ * <h2><TranslatedText text={item.title} /></h2>
+ * ```
+ *
+ * Returns the original synchronously while the translation is in flight,
+ * so titles never flash empty. No-op for English.
+ */
+export declare const TranslatedText: React.FC<TranslatedTextProps>;
+export default TranslatedText;

package/dist/i18n/HiveLanguageContext.d.ts

@@ -0,0 +1,67 @@
+import React from "react";
+import { type KitMessageKey } from "./messages";
+export type TranslateHtmlFn = (html: string, target: string) => Promise<string>;
+/** Look up a UI label in the supplied dict, with English fallback. */
+export type KitTFn = (key: KitMessageKey, vars?: Record<string, string | number>) => string;
+export interface HiveLanguageContextValue {
+    /**
+     * Two-letter language code for translating user-generated content
+     * (post bodies, comments, activity bodies). `"en"` is the no-op default —
+     * content passes through unchanged.
+     */
+    language: string;
+    /**
+     * Custom translator. Defaults to a free MyMemory-backed implementation
+     * that ships with the kit. Override to plug in DeepL, Google Translate,
+     * or any other service — receives the rendered HTML and target language,
+     * returns translated HTML.
+     */
+    translateHtml: TranslateHtmlFn;
+    /**
+     * UI label translator. Resolves a key against the merged messages dict
+     * (consumer overrides → kit built-ins → English source-of-truth).
+     */
+    t: KitTFn;
+}
+export interface HiveLanguageProviderProps {
+    /** Two-letter language code, e.g. `"en"`, `"es"`. Defaults to `"en"`. */
+    language?: string;
+    /**
+     * Optional override translator for user-generated HTML. If omitted, the
+     * kit's default MyMemory-backed implementation is used.
+     */
+    translateHtml?: TranslateHtmlFn;
+    /**
+     * Optional UI label overrides keyed by language code. Merges on top of
+     * the kit's built-in `en` + `es` dicts:
+     *
+     * ```tsx
+     * messages={{
+     *   es: { "action.follow": "Seguir cuenta" },  // override one label
+     *   fr: { "action.follow": "Suivre" },         // add a new language
+     * }}
+     * ```
+     *
+     * Missing keys for a non-English language fall back to English.
+     */
+    messages?: Record<string, Record<string, string>>;
+    children: React.ReactNode;
+}
+/**
+ * Wrap your app once with this provider so every Hive content body
+ * rendered by the kit (`<HiveDetailPost>`, comments, snaps, profile feeds,
+ * activity bodies) translates to the chosen language.
+ *
+ * ```tsx
+ * <HiveLanguageProvider language={i18n.language}>
+ *   <App />
+ * </HiveLanguageProvider>
+ * ```
+ *
+ * When `language === "en"` (the default), the provider is a no-op.
+ */
+export declare const HiveLanguageProvider: React.FC<HiveLanguageProviderProps>;
+/** Read the current Hive language + translator + label resolver from context. */
+export declare function useHiveLanguage(): HiveLanguageContextValue;
+/** Convenience hook returning just the UI label resolver. */
+export declare function useKitT(): KitTFn;

package/dist/i18n/index.d.ts

@@ -0,0 +1,5 @@
+export { HiveLanguageProvider, useHiveLanguage, useKitT, type HiveLanguageProviderProps, type HiveLanguageContextValue, type TranslateHtmlFn, type KitTFn, } from "./HiveLanguageContext";
+export { useTranslatedHtml } from "./useTranslatedHtml";
+export { useTranslatedText } from "./useTranslatedText";
+export { translateHtml, translateText } from "./translateService";
+export { BUILTIN_MESSAGES, formatMessage, type KitMessageKey, type KitMessages, } from "./messages";

package/dist/i18n/messages.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Built-in UI label translations for hive-react-kit components.
+ *
+ * Keys follow the dotted convention `area.label`. Each language is a
+ * flat Record<string, string>. Consumers can extend or override specific
+ * keys via the `messages` prop on `<HiveLanguageProvider>`:
+ *
+ * ```tsx
+ * <HiveLanguageProvider
+ *   language="es"
+ *   messages={{ es: { "action.follow": "Suivre" } }}
+ * />
+ * ```
+ *
+ * Missing keys for a non-English language fall back to the English entry,
+ * which is the source of truth for every label.
+ */
+export type KitMessageKey = "tab.blogs" | "tab.posts" | "tab.snaps" | "tab.polls" | "tab.comments" | "tab.replies" | "tab.activities" | "tab.authorRewards" | "tab.curationRewards" | "tab.growth" | "tab.followers" | "tab.following" | "tab.wallet" | "tab.votingPower" | "tab.badges" | "tab.witnessVotes" | "meta.followers" | "meta.following" | "meta.posts" | "action.follow" | "action.unfollow" | "action.ignoreAuthor" | "action.reportUser" | "action.shareProfile" | "action.cancel" | "action.confirmIgnore" | "action.processing" | "modal.ignoreAuthorTitle" | "modal.ignoreAuthorBody" | "empty.noBlogs" | "empty.noPosts" | "empty.noSnaps" | "empty.noPolls" | "empty.noComments" | "empty.noReplies" | "empty.noFollowers" | "empty.notFollowing" | "empty.noBadges" | "empty.noWitnessVotes" | "empty.noPendingAuthor" | "empty.noPendingCuration" | "empty.curationHint" | "empty.votingPowerUnavailable" | "empty.userNotFound" | "status.active" | "status.ended" | "poll.selectAnOption" | "poll.selectUpTo" | "poll.changeYourVote" | "poll.selected" | "poll.submitVote" | "poll.submitVotes" | "poll.changeVote" | "poll.submitting" | "poll.voted" | "poll.voteChangesAllowed" | "poll.voter" | "poll.voters" | "poll.option" | "poll.options" | "poll.endsIn" | "common.translating" | "common.processing" | "common.fullyCharged" | "reward.pendingAuthor" | "reward.pendingCuration" | "reward.posts" | "reward.comments" | "reward.totalHbd" | "reward.totalHp" | "reward.avgEfficiency" | "reward.post" | "reward.comment" | "vp.upvotePower" | "vp.downvotePower" | "vp.resourceCredits";
+export type KitMessages = Partial<Record<KitMessageKey, string>>;
+export declare const BUILTIN_MESSAGES: Record<string, Record<string, string>>;
+/**
+ * Format helper — replaces `{key}` placeholders with the corresponding
+ * value from `vars`. Missing vars leave the placeholder intact.
+ */
+export declare function formatMessage(template: string, vars?: Record<string, string | number>): string;

package/dist/i18n/translateService.d.ts

@@ -0,0 +1,20 @@
+/**
+ * MyMemory-backed translation service for translating Hive post / comment
+ * bodies (rendered HTML) into the user's selected app language.
+ *
+ * Free, no API key, soft daily quota. The kit ships this as the default
+ * translator — consumers can override by passing their own `translate`
+ * function to `<HiveLanguageProvider>` (e.g. DeepL, Google Translate, an
+ * authenticated MyMemory account).
+ *
+ * Heavy caching: in-memory map (session) + localStorage (cross-reload) +
+ * in-flight dedup so two views of the same body share one network call.
+ */
+/** Translate a single text string to `target` language. */
+export declare function translateText(text: string, target: string, source?: string): Promise<string>;
+/**
+ * Translate every visible text node in an HTML string to `target`. Skips
+ * text inside `<code>`, `<pre>`, `<script>`, `<style>`, `<noscript>`, and
+ * `<iframe>` so embeds and code samples render unchanged.
+ */
+export declare function translateHtml(html: string, target: string): Promise<string>;

package/dist/i18n/useTranslatedHtml.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Translate a rendered Hive post / comment body (HTML) into the language
+ * supplied by the nearest `<HiveLanguageProvider>`. Returns the original
+ * HTML for English (the source language) and synchronously falls back to
+ * the original on translation errors so the UI never looks broken.
+ *
+ * The translation is async — `loading` is true while the API request is
+ * in flight on the very first render. Subsequent renders read from cache
+ * and resolve instantly.
+ */
+export declare function useTranslatedHtml(html: string): {
+    html: string;
+    loading: boolean;
+};

package/dist/i18n/useTranslatedText.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Plain-text counterpart to `useTranslatedHtml`. Use for titles, captions,
+ * preview snippets, and any other short user-generated string that should
+ * follow the language set on `<HiveLanguageProvider>`.
+ *
+ * Returns the original synchronously while the translation API call is
+ * in flight, so titles never flash blank. Falls back to the original on
+ * error and bypasses the translator entirely for English.
+ */
+export declare function useTranslatedText(text: string | undefined | null): {
+    text: string;
+    loading: boolean;
+};