Supabase Error Translator JS

A comprehensive Supabase error code translator supporting 9 languages with ISO language codes

> DISCLAIMER: This is a private project and is NOT officially associated with, endorsed by, or affiliated with Supabase in any way. This project is maintained independently.


Table of Contents

- Overview
- Installation
- Usage
- Basic Usage
- Auto-Detect Browser Language
- Get Current Language and Supported Languages
- Override Language for Specific Translations
- Error Handling and Fallbacks
- API Reference
- Examples

- Auth Error
- Database Error
- Storage Error
- Realtime Error

- Supported Error Codes
- Roadmap
- Changelog
- Contributing
- License

Overview

This library provides translations for Supabase error codes and messages in multiple languages. It's designed to help developers create a better user experience by displaying localized error messages to users based on their preferred language.

Supported Languages

| Language | Code | Native Name |
| ---------- | ---- | ----------- |
| English | en | English |
| German | de | Deutsch |
| Spanish | es | Español |
| French | fr | Français |
| Japanese | ja | 日本語 |
| Korean | ko | 한국어 |
| Polish | pl | Polski |
| Portuguese | pt | Português |
| Chinese | zh | 中文 |

Installation

``bash
npm install supabase-error-translator-js
`

or

`bash
yarn add supabase-error-translator-js
`

Usage

$3

`typescript
import { translateErrorCode, setLanguage } from 'supabase-error-translator-js';

// Set the language (defaults to English if not set)
setLanguage('es'); // Set to Spanish

// Translate an error code
const message = translateErrorCode('email_not_confirmed', 'auth');
console.log(message); // Outputs the Spanish translation for this error code
`

$3

`typescript
import { setLanguage, translateErrorCode } from 'supabase-error-translator-js';

// Automatically detect and use the browser's language
setLanguage('auto');

// Translate an error code using the detected language
const message = translateErrorCode('invalid_credentials', 'auth');
console.log(message);
`

$3

`typescript
import { getCurrentLanguage, getSupportedLanguages } from 'supabase-error-translator-js';

// Get the currently active language
const currentLang = getCurrentLanguage();
console.log(currentLang); // e.g., 'en', 'de', etc.

// Get all supported languages
const supportedLangs = getSupportedLanguages();
console.log(supportedLangs); // ['en', 'de', 'es', 'fr', 'ja', 'ko', 'pl', 'pt', 'zh']
`

$3

`typescript
import { translateErrorCode } from 'supabase-error-translator-js';

// Translate using a specific language (without changing the default)
const message = translateErrorCode('phone_exists', 'auth', 'fr');
console.log(message); // French translation
`

Error Handling and Fallbacks

We normalize any empty or whitespace-only code to the special key unknown_error before doing any locale lookups. From there, we follow a four-step, industry-standard fallback chain:

1. Service-specific locale lookup: First try translations[target].services[service][key] - looking for the error code in the specified service in the user's language.

2. Service-specific English lookup: If not found in the target language, try translations.en.services[service][key] - looking for the error code in the specified service in English.

3. Generic locale fallback: If the service-specific code isn't found, try translations[target].unknown_error - the generic unknown error message in the user's language.

4. Generic English fallback: Finally, return translations.en.unknown_error - the generic unknown error message in English.

This enhanced fallback chain ensures that:

- Service-specific error codes are properly translated
- Blank or unrecognized codes first yield a localized "unknown error" message before falling back to English
- The system is resilient to missing translations in any language or service
- Special handling for direct "unknown_error" requests bypasses service-specific lookups for efficiency

The service parameter allows the system to correctly handle cases where the same error code exists in multiple Supabase services with different meanings and contexts.

API Reference

$3

Sets the current language for translations. If "auto" is passed, it will attempt to detect the browser's language.

- Parameters:
- lang: A supported ISO language code ('en', 'de', 'es', 'fr', 'ja', 'ko', 'pl', 'pt', 'zh') or "auto"
- Behavior:
- If an unsupported language is provided, falls back to English ('en')

$3

Translates a Supabase error code into localized text, normalizing blank or missing codes to unknown_error.

- Parameters:

- code?: The Supabase error code to translate. If undefined or empty, treated as "unknown_error".
- service: The Supabase service that generated the error:
- 'auth' - Authentication and user management errors
- 'storage' - File storage errors
- 'realtime' - Realtime subscription errors
- 'database' - Database query errors
- 'functions' - Edge Functions errors
- lang?: (Optional)
- Omitted → use currentLanguage
- "auto" → detect via detectBrowserLanguage(), fallback to 'en' if unsupported
- Any other value → if unsupported, fallback to 'en'

- Returns:
- The translated message, using this lookup chain:
1. translations[target].services[service][key]
2. translations.en.services[service][key]
3. translations[target].unknown_error
4. translations.en.unknown_error

$3

Returns the currently active language.

- Returns:
- The current language code as a string

$3

Returns an array of all supported language codes.

- Returns:
- Array of supported language codes

Examples

$3

`jsx
import React, { useState, useEffect } from 'react';
import { setLanguage, translateErrorCode } from 'supabase-error-translator-js';
import { supabase } from './supabaseClient';
import { useRouter } from 'next/navigation';

function SignupForm() {
const router = useRouter();
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const [error, setError] = useState(null);
const [isLoading, setIsLoading] = useState(false);

useEffect(() => {
// Set language
setLanguage('de');
}, []);

const handleSignup = async (e) => {
e.preventDefault();
setError(null);
setIsLoading(true);

try {
const { error } = await supabase.auth.signUp({
email,
password,
});

if (error) {
// Translate the error code from Supabase
const translatedError = translateErrorCode(error.code, 'auth');
setError(translatedError);
} else {
// Navigate to login page in Next.js 15
router.push('/login');
// Clear form
setEmail('');
setPassword('');
}
} catch (err) {
setError(translateErrorCode('unknown_error', 'auth'));
} finally {
setIsLoading(false);
}
};

return (


type="email"
value={email}
onChange={(e) => setEmail(e.target.value)}
placeholder="Email"
required
disabled={isLoading}
/>
type="password"
value={password}
onChange={(e) => setPassword(e.target.value)}
placeholder="Passwort"
required
disabled={isLoading}
/>
{/ Keep UI text in native language /}

{isLoading ? 'Wird angemeldet...' : 'Anmelden'}


);
}
`

$3

`jsx
import React, { useState, useEffect } from 'react';
import { setLanguage, translateErrorCode } from 'supabase-error-translator-js';
import { supabase } from './supabaseClient';

function ProductForm() {
const [name, setName] = useState('');
const [price, setPrice] = useState('');
const [description, setDescription] = useState('');
const [error, setError] = useState(null);
const [isSubmitting, setIsSubmitting] = useState(false);
const [successMessage, setSuccessMessage] = useState('');

useEffect(() => {
// Set language to German
setLanguage('de');
}, []);

const handleSubmit = async (e) => {
e.preventDefault();
setError(null);
setSuccessMessage('');
setIsSubmitting(true);

// Basic validation
if (!name || !price) {
setError('Bitte fülle alle Pflichtfelder aus.');
setIsSubmitting(false);
return;
}

try {
// Attempt to insert a new product into the database
const { data, error: dbError } = await supabase
.from('products')
.insert([
{
name,
price: parseFloat(price),
description,
created_at: new Date(),
},
])
.select();

if (dbError) {
// Simply translate the database error code
const translatedError = translateErrorCode(dbError.code, 'database');
setError(translatedError);
} else {
// Clear the form and show success message
setName('');
setPrice('');
setDescription('');
setSuccessMessage('Produkt erfolgreich gespeichert!');
}
} catch (err) {
// Handle unexpected errors
setError(translateErrorCode('unknown_error', 'database'));
} finally {
setIsSubmitting(false);
}
};

return (


export default ProductForm;
`

$3

`jsx
import React, { useState, useEffect } from 'react';
import { setLanguage, translateErrorCode } from 'supabase-error-translator-js';
import { supabase } from './supabaseClient';

function FileUploader() {
const [file, setFile] = useState(null);
const [error, setError] = useState(null);
const [isUploading, setIsUploading] = useState(false);

useEffect(() => {
// Set language
setLanguage('es');
}, []);

const handleFileChange = (event) => {
setFile(event.target.files);
setError(null); // Clear previous errors
};

const handleUpload = async () => {
if (!file) {
setError('Por favor, selecciona un archivo para subir.'); // Example of a non-Supabase error
return;
}

setIsUploading(true);
setError(null);

try {
const { data, error: uploadError } = await supabase.storage
.from('your-bucket-name') // Replace with your bucket name
.upload(public/${file.name}, file);

if (uploadError) {
// translate error code if existing
const translatedError = translateErrorCode(uploadError.code, 'storage');
setError(translatedError);
} else {
console.log('File uploaded successfully:', data);
// Handle success (e.g., show a success message or clear the form)
setFile(null);
}
} catch (err) {
// Assuming a general error during the async operation should use unknown_error
setError(translateErrorCode('unknown_error', 'storage'));
} finally {
setIsUploading(false);
}
};

return (


`jsx
import React, { useState, useEffect } from 'react';
import { setLanguage, translateErrorCode } from 'supabase-error-translator-js';
import { supabase } from './supabaseClient';

function RealtimeListener() {
const [realtimeError, setRealtimeError] = useState(null);
const [messages, setMessages] = useState([]); // To show received messages

useEffect(() => {
// Set language
setLanguage('fr');

// Subscribe to a channel
const channel = supabase
.channel('my-realtime-channel') // Replace with your channel name
.on('broadcast', { event: 'my-event' }, (payload) => {
console.log('Realtime message received:', payload);
setMessages((prevMessages) => [...prevMessages, payload.payload]);
})
// Error handling for the channel
.subscribe((status, err) => {
if (status === 'CHANNEL_ERROR') {
console.error('Realtime Channel Error:', err);
if (err) {
// Check for error code
// Attempt to translate the Realtime error code
const translatedError = translateErrorCode(err.code, 'realtime');
setRealtimeError(translatedError);
} else {
// Fallback for unexpected Realtime error structures
setRealtimeError(translateErrorCode('unknown_error', 'realtime'));
}
} else if (status === 'TIMED_OUT') {
// Handle specific Realtime statuses if needed
setRealtimeError('Connexion Realtime expirée. Veuillez réessayer.');
}
});

// Clean up subscription on component unmount
return () => {
supabase.removeChannel(channel);
};
}, []); // Empty dependency array means this effect runs once on mount

return (


- 🚨 BREAKING CHANGE: Migrated to proper ISO 639-1 language codes
- jp → ja (Japanese)
- kr → ko (Korean)
- cn → zh (Chinese)
- Fixed behavior: translateErrorCode() without lang parameter now correctly uses currentLanguage` instead of browser detection
- All existing translations maintained with new language codes
- Improved compliance with international standards

Version: 2.2.0 - 27.05.2025

- Added support for 5 new languages:
- Japanese (jp) - 日本語
- Korean (kr) - 한국어
- Polish (pl) - Polski
- Portuguese (pt) - Português
- Chinese (cn) - 中文
- Now supporting 9 total languages for comprehensive global coverage

Version: 2.1.0 - 09.05.2024

- Added support for database errors (PostgreSQL and PostgREST)

For detailed release notes and migration guides, see the full CHANGELOG.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

See CONTRIBUTING.md for guidelines on how to contribute to this project.

License

This project is licensed under the MIT License - see the LICENSE file for details.