SDK Reference

Simplist provides comprehensive multilingual support with 80+ languages, automatic browser language detection, and smart content variant management.

Simplist supports 80+ languages including:

  • Popular: English, French, Spanish, German, Italian, Portuguese, Russian
  • Asian: Japanese, Korean, Chinese (Simplified/Traditional), Thai, Vietnamese
  • Middle Eastern: Arabic, Hebrew, Persian
  • And many more...

See the complete list in the Language enum.

Automatically detect the user's preferred language from browser settings.

Method Signature
detectUserLanguage(): LanguageCode
import { detectUserLanguage } from "@simplist.blog/sdk"

const userLang = detectUserLanguage()
console.log(userLang) // 'en', 'fr', 'es', etc.

Get a specific language variant or fall back to the default.

Method Signature
getVariantOrDefault(article: Article, lang: LanguageCode, fallbackLang?: LanguageCode): ArticleVariant | Article
import { getVariantOrDefault } from "@simplist.blog/sdk"

const frenchVersion = getVariantOrDefault(article, 'fr', 'en')
console.log(frenchVersion.title)

Get the best matching variant based on user's language preference.

Method Signature
getBestMatchingVariant(article: Article, userLang?: LanguageCode, fallbackLang?: LanguageCode): ArticleVariant | Article
import { getBestMatchingVariant } from "@simplist.blog/sdk"

// Automatically uses browser language
const localizedArticle = getBestMatchingVariant(article)
console.log(localizedArticle.title) // Title in user's language

// Force a specific language
const frenchArticle = getBestMatchingVariant(article, 'fr')
console.log(frenchArticle.title) // Title in French (or fallback)

// Force language with custom fallback
const spanishArticle = getBestMatchingVariant(article, 'es', 'pt')
console.log(spanishArticle.title) // Spanish, fallback to Portuguese

Check if an article has a translation in a specific language.

Method Signature
hasVariant(article: Article, lang: LanguageCode): boolean
import { hasVariant } from "@simplist.blog/sdk"

if (hasVariant(article, 'fr')) {
  console.log('French version available!')
}

Get all available languages for an article.

Method Signature
getAllLanguages(article: Article): LanguageCode[]
import { getAllLanguages } from "@simplist.blog/sdk"

const languages = getAllLanguages(article)
console.log(languages) // ['en', 'fr', 'es', 'de']

Check if an article has any translations.

Method Signature
isMultilingual(article: Article): boolean
import { isMultilingual } from "@simplist.blog/sdk"

if (isMultilingual(article)) {
console.log('This article has translations')
}

The VariantSelector class provides a consistent way to manage article variants across your application.

Method Signature
new VariantSelector(options?: { defaultLanguage?: LanguageCode, userLanguage?: LanguageCode }): VariantSelector

MethodDescriptionReturns
Get article content in preferred languagestring
Get article title in preferred languagestring
Get article excerpt in preferred languagestring | null
Get complete article variantArticleVariant | Article
Get cover image for variantstring | null
Get the selected language for articleLanguageCode
Update user language preferencevoid
Update default fallback languagevoid

import { VariantSelector } from "@simplist.blog/sdk"

const selector = new VariantSelector({
  defaultLanguage: 'en',
  userLanguage: 'fr'
})

// Get localized content
const title = selector.getTitle(article)
const content = selector.getContent(article)
const excerpt = selector.getExcerpt(article)

// Get full variant
const variant = selector.getFullContent(article)
console.log(variant.lang) // 'fr'
console.log(variant.wordCount) // Word count for French version

// Change language dynamically
selector.setUserLanguage('es')
const spanishTitle = selector.getTitle(article)

"use client";

import { getAllLanguages, VariantSelector } from "@simplist.blog/sdk";
import { useState } from "react";
import type { Article, LanguageCode } from "@simplist.blog/sdk";

export function LanguageSwitcher({ article }: { article: Article }) {
  const availableLanguages = getAllLanguages(article)
  const [selectedLang, setSelectedLang] = useState("en")

  const selector = new VariantSelector({
    defaultLanguage: "en",
    userLanguage: selectedLang
  })

  const handleLanguageChange = (lang: string) => {
    setSelectedLang(lang)
    selector.setUserLanguage(lang as LanguageCode)
  }

  return (
    <div>
      <select value={selectedLang} onChange={(e) => handleLanguageChange(e.target.value)}>
        {availableLanguages.map(lang => (
          <option key={lang} value={lang}>
            {lang.toUpperCase()}
          </option>
        ))}
      </select>

      <article>
        <h1>{selector.getTitle(article)}</h1>
        <p>{selector.getExcerpt(article)}</p>
        <div dangerouslySetInnerHTML={{ __html: selector.getContent(article) }} />
      </article>
    </div>
  )
}

PropertyTypeDescriptionDefault
lang*LanguageCodeLanguage code-
title*stringTranslated title-
excerptstring | nullTranslated excerpt-
content*stringTranslated content (Markdown)-
coverImagestring | nullCover image for this variant-
wordCount*numberWord count-
characterCount*numberCharacter count-
readTimeMinutes*numberReading time estimate-
createdAt*stringVariant creation date-
updatedAt*stringLast update date-

import { Language } from "@simplist.blog/sdk"

// Popular languages
Language.ENGLISH // 'en'
Language.FRENCH // 'fr'
Language.SPANISH // 'es'
Language.GERMAN // 'de'
Language.ITALIAN // 'it'
Language.PORTUGUESE // 'pt'
Language.RUSSIAN // 'ru'
Language.JAPANESE // 'ja'
Language.KOREAN // 'ko'
Language.CHINESE // 'zh'
Language.ARABIC // 'ar'
Language.HINDI // 'hi'

// And 68+ more languages...

  • hreflang tags: Add alternate language links for SEO
  • Language attribute: Set <html lang="..."> for each variant
  • Sitemap: Include all language variants in sitemap
  • URL structure: Use language prefix (e.g., /fr/article-slug)
// Generate hreflang tags
import { getAllLanguages } from "@simplist.blog/sdk"

export function generateHreflangTags(article: Article, baseUrl: string) {
const languages = getAllLanguages(article)

  return languages.map(lang => ({
    rel: 'alternate',
    hrefLang: lang,
    href: `${baseUrl}/${lang}/${article.slug}`
  }))
}

  • Fallback language: Always set a default/fallback language (usually English)
  • User preference: Remember user's language choice in localStorage/cookies
  • Auto-detection: Use browser language for initial selection
  • Translation indicators: Show which languages are available

Quick Help

Use detectUserLanguage() which checks the Accept-Language header. In Next.js, access it via headers().get('accept-language'). Always provide a fallback language.
getVariantOrDefault() automatically falls back to the default language if the requested variant doesn't exist. This ensures users always see content.
No, all language variants share the same slug. Use the slug for routing and serve different content based on the user's language preference.
Edit on GitHub
Previous
SEO API
Next
Fetch Articles

Command Palette

Search for a command to run...