Overview
The Stringboot Web SDK provides a simple API for fetching and managing localized strings. This guide covers the core functionality for both vanilla JavaScript and React applications.
Fetching Strings
Using Watchers (Recommended)
Watchers automatically update your UI when the language changes. This is the recommended approach for vanilla JavaScript:
import StringBoot from '@stringboot/web-sdk';
// Set up watchers that automatically update on language change
StringBoot.watch('welcome_message', (value) => {
document.getElementById('welcome').textContent = value;
});
StringBoot.watch('app_title', (value) => {
document.getElementById('title').textContent = value;
});
StringBoot.watch('cta_button', (value) => {
document.getElementById('cta').textContent = value;
});
Watchers ensure your UI stays in sync when users change languages. Set them up once during initialization.
Manual String Fetching
For one-off string retrievals, use the get() method:
import StringBoot from '@stringboot/web-sdk';
async function loadStrings() {
try {
const title = await StringBoot.get('page_title');
const description = await StringBoot.get('page_description');
document.getElementById('title').textContent = title;
document.getElementById('desc').textContent = description;
} catch (error) {
console.error('Failed to load strings:', error);
}
}
Language Switching
Change the current language dynamically:
import StringBoot from '@stringboot/web-sdk';
const languageSelect = document.getElementById('language');
languageSelect.addEventListener('change', async (e) => {
const newLanguage = e.target.value;
try {
// Change language - watchers will auto-update UI
await StringBoot.changeLanguage(newLanguage);
console.log(`✓ Language changed to ${newLanguage}`);
} catch (error) {
console.error('Language change failed:', error);
}
});
When you change languages, all watchers automatically receive updated strings. You don’t need to manually update your UI.
Error Handling
Always use try/catch to handle errors gracefully:
import StringBoot from '@stringboot/web-sdk';
async function fetchString() {
try {
const message = await StringBoot.get('welcome_message');
document.getElementById('welcome').textContent = message;
} catch (error) {
console.error('Failed to fetch string:', error);
// Show fallback or error message
document.getElementById('welcome').textContent = 'Welcome';
}
}
Offline Support
The SDK automatically works offline using cached data:
// Strings work automatically even when offline
const title = await StringBoot.get('app_title');
// Returns cached value if available
The SDK caches all fetched strings locally. Your app will continue to work even without an internet connection.
Complete Example
Here’s a complete vanilla JavaScript application:
import StringBoot from '@stringboot/web-sdk';
async function initApp() {
try {
// Initialize SDK
await StringBoot.initialize({
apiToken: import.meta.env.VITE_STRINGBOOT_TOKEN,
baseUrl: 'https://api.stringboot.com',
defaultLanguage: 'en',
debug: false
});
// Set up watchers for automatic UI updates
StringBoot.watch('page_title', (value) => {
document.getElementById('title').textContent = value;
});
StringBoot.watch('welcome_message', (value) => {
document.getElementById('welcome').textContent = value;
});
StringBoot.watch('cta_button', (value) => {
document.getElementById('cta-btn').textContent = value;
});
// Set up language switcher
const langSelect = document.getElementById('language');
langSelect.addEventListener('change', async (e) => {
try {
await StringBoot.changeLanguage(e.target.value);
} catch (error) {
console.error('Language change failed:', error);
}
});
console.log('✓ App initialized successfully');
} catch (error) {
console.error('✗ Initialization failed:', error);
}
}
// Initialize on page load
initApp();
API Reference
Core Methods
| Method | Description | Returns |
|---|
initialize(config) | Initialize the SDK | Promise<void> |
get(key) | Fetch a single string | Promise<string> |
watch(key, callback) | Watch for string changes | void |
changeLanguage(code) | Switch to a different language | Promise<void> |
Configuration Options
| Option | Type | Required | Default |
|---|
apiToken | string | Yes | - |
baseUrl | string | No | https://api.stringboot.com |
defaultLanguage | string | No | en |
debug | boolean | No | false |
enableIntegrityCheck | boolean | No | false |
What’s Next?
