api_localization

FTable API Reference - Localization

FTable can be easily localized using ready localization files or custom messages.

---

With Localization Files

You can localize FTable by including a localization script after the FTable script file:

<script type="text/javascript" src="/Scripts/ftable/ftable.js"></script>
<script type="text/javascript" src="/Scripts/ftable/localization/ftable.tr.js"></script>

The example above shows Turkish (tr) localization. You can find localization files for various languages or create your own. If you create a new localization file, consider sharing it with the FTable community on GitHub.

Note: Localization files should be loaded after the main FTable script but before initializing any FTable instances.

---

With Custom Localized Messages

You can use the messages option to localize a FTable instance during initialization. The default value of the messages option is:

messages: {
    serverCommunicationError: 'An error occurred while communicating with the server.',
    loadingMessage: 'Loading records...',
    noDataAvailable: 'No data available!',
    addNewRecord: 'Add new record',
    editRecord: 'Edit Record',
    areYouSure: 'Are you sure?',
    deleteConfirmation: 'This record will be deleted. Are you sure?',
    save: 'Save',
    saving: 'Saving',
    cancel: 'Cancel',
    deleteText: 'Delete',
    deleting: 'Deleting',
    error: 'Error',
    close: 'Close',
    cannotLoadOptionsFor: 'Cannot load options for field {0}',
    pagingInfo: 'Showing {0}-{1} of {2}',
    pageSizeChangeLabel: 'Row count',
    gotoPageLabel: 'Go to page',
    canNotDeletedRecords: 'Cannot delete {0} of {1} records!',
    deleteProggress: 'Deleted {0} of {1} records, processing...',
    sortingInfoPrefix: 'Sorting applied: ',
    sortingInfoSuffix: '',
    ascending: 'Ascending',
    descending: 'Descending',
    sortingInfoNone: 'No sorting applied',
    csvExport: 'CSV',
    printTable: '🖨️  Print'
}

Example: Turkish Localization

Here's an example of Turkish localization:

const turkishMessages = {
    loadingMessage: 'Kayıtlar yükleniyor...',
    noDataAvailable: 'Hiç kayıt bulunmamaktadır!',
    addNewRecord: 'Yeni kayıt ekle',
    editRecord: 'Kayıt düzenle',
    areYouSure: 'Emin misiniz?',
    deleteConfirmation: 'Bu kayıt silinecektir. Emin misiniz?',
    save: 'Kaydet',
    saving: 'Kaydediyor',
    cancel: 'İptal',
    deleteText: 'Sil',
    deleting: 'Siliyor',
    error: 'Hata',
    close: 'Kapat',
    cannotLoadOptionsFor: '{0} alanı için seçenekler yüklenemedi!',
    pagingInfo: 'Gösterilen: {0}-{1}, Toplam: {2}',
    canNotDeletedRecords: '{1} kayıttan {0} adedi silinemedi!',
    deleteProgress: '{1} kayıttan {0} adedi silindi, devam ediliyor...',
    pageSizeChangeLabel: 'Satır sayısı',
    gotoPageLabel: 'Sayfaya git',
    sortingInfoPrefix: 'Sıralama uygulandı: ',
    ascending: 'Artan',
    descending: 'Azalan',
    sortingInfoNone: 'Sıralama uygulanmadı',
    csvExport: 'CSV',
    printTable: '🖨️  Yazdır'
};

Setting Localized Messages for a FTable Instance

To set localized messages for a specific FTable instance during initialization:

const table = new FTable('#PersonTable', {
    messages: turkishMessages,
    // ... other options
});

Setting Localized Messages Globally

To set localized messages for all FTable instances on your website, you can extend the default messages before creating any tables:

Method 1: Using Static Method (if available)

// Set global messages before creating any FTable instances
FTable.setMessages(turkishMessages);

// Now all new FTable instances will use Turkish messages
const table1 = new FTable('#Table1', { /*...*/ });
const table2 = new FTable('#Table2', { /*...*/ });

Method 2: Using Prototype Extension

// Extend the default messages
if (FTable.prototype && FTable.prototype.defaultOptions) {
    Object.assign(FTable.prototype.defaultOptions.messages, turkishMessages);
}

// Or if the structure is different:
FTable.defaultMessages = Object.assign(FTable.defaultMessages || {}, turkishMessages);

Method 3: Creating a Localization Helper

function createLocalizedFTable(selector, options = {}) {
    return new FTable(selector, {
        messages: turkishMessages,
        ...options
    });
}

// Usage
const table = createLocalizedFTable('#PersonTable', {
    title: 'Kişiler Tablosu',
    actions: { /*...*/ },
    fields: { /*...*/ }
});

---

Creating Custom Localization Files

You can create your own localization files for sharing with the community. Here's an example structure:

File: ftable.fr.js (French localization)

/**
 * FTable French Localization
 */
(function() {
    if (typeof FTable !== 'undefined') {
        const frenchMessages = {
            serverCommunicationError: 'Une erreur est survenue lors de la communication avec le serveur.',
            loadingMessage: 'Chargement des enregistrements...',
            noDataAvailable: 'Aucune donnée disponible !',
            addNewRecord: 'Ajouter un nouvel enregistrement',
            editRecord: 'Modifier l\'enregistrement',
            areYouSure: 'Êtes-vous sûr ?',
            deleteConfirmation: 'Cet enregistrement sera supprimé. Êtes-vous sûr ?',
            save: 'Enregistrer',
            saving: 'Enregistrement en cours',
            cancel: 'Annuler',
            deleteText: 'Supprimer',
            deleting: 'Suppression en cours',
            error: 'Erreur',
            close: 'Fermer',
            cannotLoadOptionsFor: 'Impossible de charger les options pour le champ {0}',
            pagingInfo: 'Affichage de {0}-{1} sur {2}',
            pageSizeChangeLabel: 'Nombre de lignes',
            gotoPageLabel: 'Aller à la page',
            canNotDeletedRecords: 'Impossible de supprimer {0} enregistrement(s) sur {1} !',
            deleteProggress: '{0} enregistrement(s) supprimé(s) sur {1}, traitement en cours...',
            sortingInfoPrefix: 'Tri appliqué : ',
            sortingInfoSuffix: '',
            ascending: 'Croissant',
            descending: 'Décroissant',
            sortingInfoNone: 'Aucun tri appliqué',
            csvExport: 'CSV',
            printTable: '🖨️  Imprimer'
        };

        // Set as default messages
        if (FTable.setMessages) {
            FTable.setMessages(frenchMessages);
        } else if (FTable.prototype && FTable.prototype.defaultOptions) {
            Object.assign(FTable.prototype.defaultOptions.messages, frenchMessages);
        }
    }
})();

---

Message Placeholders

Some localization messages support placeholders that will be replaced with dynamic values:

• {0}, {1}, {2}, etc. - Positional placeholders
• cannotLoadOptionsFor: {0} = field name
• pagingInfo: {0} = start index, {1} = end index, {2} = total count
• canNotDeletedRecords: {0} = failed count, {1} = total count
• deleteProggress: {0} = completed count, {1} = total count

Example with Custom Placeholder Handling

const customMessages = {
    // Standard placeholder
    pagingInfo: 'Showing {0}-{1} of {2}',
    
    // Custom message with more context
    pagingInfoDetailed: 'Displaying records {0} to {1} out of {2} total entries',
    
    // You can also create helper functions for complex formatting
    formatPagingInfo: function(start, end, total) {
        return `Showing ${start}-${end} of ${total} records`;
    }
};

---

Localization Best Practices

1. Test All UI Elements

When creating localizations, make sure to test:

• All form dialogs (create, edit, delete confirmation)
• Error messages
• Paging controls
• Sorting indicators
• Export/print buttons
• Loading states

2. Consider Text Length

Different languages may have significantly different text lengths. Test your localization with:

• Very long translations
• Very short translations
• Languages that read right-to-left (if applicable)

3. Date and Number Formatting

Remember that FTable may also need locale-specific formatting for:

• Date displays
• Number formatting
• Currency (if applicable)

const table = new FTable('#PersonTable', {
    messages: germanMessages,
    defaultDateLocale: 'de-DE', // German date formatting
    // ... other options
});

4. Accessibility

Ensure your localized messages maintain accessibility:

• Screen reader friendly text
• Proper ARIA labels
• Clear, descriptive button text

---

Contributing Localizations

If you create a localization file, consider contributing it back to the FTable project:

1. Fork the FTable repository
2. Add your localization file to the localization/ directory
3. Follow the naming convention: ftable.[language-code].js
4. Submit a pull request

Your contribution will help make FTable accessible to more developers worldwide!