Over the Air (Strings)

Con l'SDK, l'app verifica regolarmente la presenza di traduzioni aggiornate e le scarica in background.

Controlla regolarmente le ultime versioni dell'SDK per Android, soprattutto considerando gli aggiornamenti.

Se le traduzioni non vengono aggiornate:

Se si utilizza la versione sbagliata di una traduzione, assicurarsi che sia disponibile una versione con le traduzioni più recenti e la versione dell'app corrente e che sia impostato il versionName per l'app e che si utilizzi il formato <major>.<minor>.<point>.

Requisiti

Includi l'SDK

Aggiungi un nuovo archivio alla root build.gradle:

allprojects {
    repositories {
        ...
        maven { url "https://maven.download.phrase.com" }
    }
}

Aggiungi la libreria come dipendenza:

dependencies {
    implementation "com.phrase.android:ota-sdk:3.5.0"
    ...
}

Supporto Jetpack Compose

Per abilitare il supporto Jetpack Compose per le traduzioni OTA, segui i passaggi riportati di seguito:

Configurazione

Inizializza l'SDK nella classe applicazione e aggiungi l'ID distribuzione e la chiave privata d'ambiente. Le classi ereditate dall'applicazione dovrebbero sovrascrivere attackBaseContext per abilitare traduzioni al di fuori del contesto di attività:

public class MainApplication extends Application {
  @Override
  public void onCreate() {
      super.onCreate();
      Phrase.setup(this, "DISTRIBUTION_ID", "ENVIRONMENT_TOKEN");
      Phrase.updateTranslations();
  }

  @Override
  protected void attachBaseContext(Context newBase) {
    super.attachBaseContext(Phrase.wrapApplicationContext(newBase));
  }  
}

Inietta l'SDK in ogni attività, ad esempio creando un'attività di base da cui tutte le altre attività ereditano:

public class BaseActivity extends AppCompatActivity {
  @NonNull
  @Override
  public AppCompatDelegate getDelegate() {
    return Phrase.getDelegate(this, super.getDelegate());
  }
}

Le traduzioni possono essere utilizzate come al solito nei layout:

<TextView android:text="@string/translation_key" />

E codice interno:

TextView text = (TextView) findViewById(R.id.text_id);
text.setText(R.string.translation_key);

Alcune librerie non supportano lo srotolamento automatico del contesto e si aspettano una classe specifica. In questo caso l’avvolgimento del contesto nei componenti Jetpack Compose può essere disabilitato con:

Phrase(contextWrapping = false) {
    Text( text = phraseString(R.string.test) )
}

Configurazioni per i livelli di registro:

Modifica lingua

Se non si utilizza la lingua del sistema, è possibile impostare una lingua diversa nel metodo setLocaleCode. Il codice della lingua (impostazioni locali) dev’essere presente in una versione.

Phrase.setLocaleCode("fr");
Phrase.updateTranslations();

Versione dell'app personalizzata

L'SDK utilizza la versione dell'app per impostazione predefinita per restituire una versione che corrisponda ai vincoli di rilascio per la versione min e max. La versione dell'app deve usare il controllo delle versioni semantico, altrimenti la traduzione non viene aggiornata. Se l'app non usa il controllo delle versioni semantico, è possibile sostituire manualmente la versione dell'app utilizzata.

Esempio:

Phrase.setAppVersion("3.2.4");

La versione deve essere impostata prima di chiamare updateTranslations( ).

Timeout impostato

Il timeout predefinito per i download di traduzioni è impostato su 10s.

L’impostazione predefinita può essere modificata con:

Phrase.setTimeout(10000); // Timeout in milliseconds

Aggiorna richiamata

Se è necessaria la gestione di aggiornamenti della traduzione riusciti, allega un gestore della richiamata:

Phrase.updateTranslations(new TranslationsSyncCallback() {
    @Override
    public void onSuccess(boolean translationsChanged) {
    }

    @Override
    public void onFailure() {
    }
});

Gli aggiornamenti della traduzione possono anche essere attivati manualmente. Le traduzioni recuperate vengono visualizzate all’Avanti lancio dell’applicazione.

Per rendere immediatamente disponibili le traduzioni più recenti, usa il metodo Phrase.applyPendingUpdates(). Questo può essere combinato con l'ascolto degli aggiornamenti della traduzione:

Phrase.updateTranslations(new TranslationsSyncCallback() {
    @Override
    public void onSuccess(boolean translationsChanged) {
      if(translationsChanged) {
         Phrase.applyPendingUpdates()
        // Custom logic to refresh UI
      }
    }

    @Override
    public void onFailure() {
    }
});

L'interfaccia utente non mostra automaticamente le traduzioni e deve essere ricreata.

Configura data center USA

È supportato anche il data center phrase USA. Il data center USA può essere configurato chiamando:

Phrase.setHost("https://ota.us.phrase.com/")

Fallback

Se non è possibile raggiungere phrase a causa di una connessione di rete mancante del cliente o di un'interruzione del servizio, l'SDK utilizza le traduzioni in bundle dal file di risorse. Si consiglia di aggiornare regolarmente le traduzioni in bundle nell'app. L'SDK memorizza anche nella cache le traduzioni localmente sul dispositivo. Se tale cache esiste, verrà utilizzata fino alla traduzione Avanti aggiornata.

L'SDK usa la versione più recente per le traduzioni. Se il versionName per l'app è impostato, verrà utilizzata la versione più recente che soddisfa le restrizioni di versione.

Aggiungi una nuova lingua

Creazione della nuova lingua in phrase e creare di una nuova versione. L'SDK recupera la lingua quando questa è la lingua del dispositivo di un utente. È consigliabile aggiungere regolarmente un nuovo strings.xml per i file di nuove lingue quando si rilascia una nuova versione dell'app o gli utenti vedranno solo le traduzioni di failback determinate da Android al primo avvio dell'app.

Audit

L'SDK è di origine chiusa e non può essere visualizzato o modificato. Se si tratta di un requisito dell'organizzazione, possono essere forniti audit. Contattaci per maggiori dettagli se necessario.

Supporto visualizzazione personalizzata

Le visualizzazioni personalizzate possono essere tradotte utilizzando attributi in stile. Poiché TypedArray non consente la sovrascrittura delle risorse, sono necessarie lievi modifiche nella visualizzazione personalizzata:

Esempio di app

https://github.com/phrase/android-sdk-example

Con l'SDK, l'app verifica regolarmente la presenza di traduzioni aggiornate e le scarica in background.

Requisiti

Questa libreria dipende dalla versione 0.18.0 della libreria intl di Flutter.Segui la loro guida per aggiungere il supporto alle localizzazioni all'app.

Installazione

Aggiungi phrase a pubspec.yaml:

dependencies:
  phrase: ^2.5.1 
  ...
  intl: ^0.18.0
  flutter_localizations:
    sdk: flutter
  ...

flutter:
  generate: true
  ...

Come nella libreria intl, la generazione di codice viene usata per elaborare i file ARB. Esegui questo comando per aggiornare:

flutter pub run phrase

Utilizzando build_runner:

flutter pub run build_runner watch

Utilizzo

Inizializza phrase nel file main.dart:

import 'package:flutter/material.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';
import 'package:flutter_gen/gen_l10n/phrase_localizations.dart';
import 'package:phrase/phrase.dart';

void main() {
  Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]");
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: "Flutter Demo",
      //..
      localizzazioniDelegati: PhraseLocalizations.localizationsDelegates,
      Locali supportati: PhraseLocalizations.supportedLocales,
    );
  }
}

Accedi ai messaggi con:

Text(AppLocalizations.of(context)!.helloWorld);

Personalizzazione

Aggiorna comportamento

Le traduzioni OTA vengono aggiornate ogni volta che si lancia l'app. Per disabilitare ciò:

Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]", 
    checkForUpdates: false);

Per aggiornare manualmente:

Phrase.updateTranslations(context).then((_) => print("Done!"));

Versione dell'app personalizzata

L'SDK utilizza la versione dell'app per impostazione predefinita per restituire una versione che corrisponda ai vincoli di rilascio per la versione min e max. La versione dell'app deve usare il controllo delle versioni semantico altrimenti non verrà restituito alcun aggiornamento della traduzione. Se l’app non usa il controllo delle versioni semantico, la versione dell’app può essere sovrascritta manualmente: è possibile sostituire manualmente la versione dell’app:

Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]",
    customAppVersion: "1.2.3");

Configura data center USA

È supportato anche il data center phrase USA. Il data center statunitense può essere selezionato passando il parametro hostname API rilevante nella configurazione dell’SDK:

Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]", host: PhraseHost.us);

Esempio di app

https://github.com/phrase/flutter_sdk_example

Con l'SDK, l'app verifica regolarmente la presenza di traduzioni aggiornate e le scarica in background.

È supportato anche Mac Catalyst.

L'SDK può essere installato manualmente o tramite Swift Package Manager, Carthage o Cocoa Pods.

Se le traduzioni non vengono aggiornate:

Se si utilizza la versione sbagliata di una traduzione, assicurarsi che sia disponibile una versione con le traduzioni più recenti e la versione dell'app corrente.

Swift Package Manager

Aggiungi l’URL dell’archivio pubblico (https://GitHub.com/Phrase/ios-sdk/). Xcode gestisce automaticamente il resto dell'installazione.

Cartagine

Aggiungi la seguente riga nel tuo Cartfile:

binary "https://raw.githubusercontent.com/phrase/ios-sdk/master/PhraseSDK.json" ~> 3.0.0

Esegui Carthage Update e aggiungi PhraseApp.framework al tuo progetto come descritto nella documentazione Carthage.

Cialde di cacao

Aggiungi la seguente riga nel tuo Podfile:

pod 'PhraseSDK'

Esegui installazione pod. Se sei nuovo su CocoaPods, consulta la loro documentazione.

Installazione manuale

Segui questi passaggi:

Configurazione

Si consiglia di chiamare entrambe le funzioni all'interno dell'AppDelegate nel metodo applicationDidFinishLaunchingWithOptions.

Obiettivo-C

Integrare l’SDK nell’applicazione Objective-C:

@import PhraseSDK;

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  [[Phrase shared] setDebugMode:true]; // Optional

  [[Phrase shared] setupWithDistributionID:@"Your Distribution ID"
                         environmentSecret:@"Your Environment Secret"];

  // OR:
  //
  //  [[Phrase shared] setupWithDistributionID:@"Your Distribution ID"
  //                         environmentSecret:@"Your Environment Secret"
  //                                   timeout:10];

  // Update translations using callback block:
  [[Phrase shared] updateTranslationsWithCompletionHandler:^(BOOL updated, NSError* error){
    NSLog(@"Updated: %@", updated ? @"true" : @"false");

    if (error) {
      NSLog(@"Domain: %@ Code: %ld Message: %@", error.domain, (long)error.code, error.localizedDescription);
    } else {
      NSLog(@"No error");
    }

    // Translate via bundle proxy:
    NSString *translation = NSLocalizedString(@"layouts.application.about", @"");
    NSLog(@"NSLocalizedString via bundle proxy: %@", translation);

    // OR:
    //
    // Translate using fallback method:
    NSString *otherTranslation = [[Phrase shared]
                                  localizedStringForKey:@"layouts.application.about" value:NULL table:NULL];
    NSLog(@"Phrase.shared localizedStringForKey: %@", otherTranslation);
  }];

  // OR:
  //
  // [[Phrase shared] updateTranslationsWithCompletionHandler:NULL]; // ignore result and errors (not recommended)

  // [...] Your other code
  
  return YES;
}

Disabilita scorrimento

Per disabilitare lo swizzling, impostare PhraseSDKMainBundleProxyDisabled su YES nel file Info.plist.

Quando lo swizzling è disabilitato, le traduzioni aggiornate non vengono più visualizzate. La traduzione verrà comunque sincronizzata se viene chiamato updateTranslation ed è possibile accedervi con il metodo Phrase.localizedString().

Gestione della versione dell'app

Per determinare quale versione deve essere restituita, l'SDK richiede una versione semantica dell'app in modo che le traduzioni vengano aggiornate.

L'SDK tenta di ottenere una versione semantica nel modo seguente:

Se CFBundleShortVersionString manca o non può essere creato con una versione semantica insieme a CFBundleVersion, l'SDK invia il messaggio PhraseSetupError.appVersionNotSemantic.

Disabilita traduzione per tabelle multiple

Per impedire a OTA di tradurre altre tabelle nel bundle principale di iOS diverse dalla tabella Localizzabile predefinita, impostare la seguente opzione:

Phrase.shared.configuration.ignoreOtherTables = true

Chiamate

Allega un gestore di richiamate per gestire gli aggiornamenti della traduzione riusciti:

Phrase.shared.updateTranslation { result in
            switch result {
            case .success(let updated):
            case .failure:
            }
        }

Modalità debug

Se sono necessarie ulteriori informazioni, abilitare la modalità Debug per ottenere una registrazione aggiuntiva di PhraseSDK.framework nella console:

Phrase.shared.configuration.debugMode = true

Imposta il timeout per le richieste

Imposta un timeout per le richieste contro phrase chiamando:

Phrase.shared.configuration.timeout = TimeInterval(20)

Il timeout predefinito è di 10 secondi e le connessioni che richiedono più di 10 secondi verranno chiuse.

Fornisci la sostituzione manuale della lingua

Se non si utilizza la lingua del sistema come impostazioni locali, è possibile impostare impostazioni locali diverse nella chiamata iniziale. Il codice delle impostazioni locali deve essere presente in una versione di phrase:

Phrase.shared.configuration.localeOverride = "en-US"

Fallback

Se non è possibile recuperare nuove traduzioni da phrase tramite l'SDK, vengono utilizzati i file di traduzione più recenti ricevuti dall'installazione. Se l'app non ha mai ricevuto nuovi file da phrase, usa i file di traduzione compilati dall'app. Ciò evita errori in caso di difficoltà tecniche o errori di rete. Si consiglia di mantenere aggiornati i file di traduzione compilati nell'app con ogni versione.

Audit

L'SDK è di origine chiusa e non può essere visualizzato o modificato. Se si tratta di un requisito dell'organizzazione, possono essere forniti audit. Contattaci per maggiori dettagli se necessario.

Con l'SDK, l'app verifica regolarmente la presenza di traduzioni aggiornate e le scarica in background.

La libreria per le traduzioni OTA funziona solo con la libreria react-i18next.

Per installare React Native SDK, segui i passaggi riportati di seguito:

File di esempio i18next.js

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import ChainedBackend from "i18next-chained-backend";
import resourcesToBackend from "i18next-resources-to-backend";
import translationEN from "./locales/en/translation.json";
import translationRU from "./locales/ru/translation.json";
import Phrase from "react-native-phrase-sdk";

const localResources = {
  en: {
    translation: translationEN,
  },
  ru: {
    translation: translationRU,
  },
};

let phrase = new Phrase(
    "YOUR_DISTRIBUTION_ID",
    "YOUR_ENVIRONMENT_ID",
    require('./package.json').version,
    "i18next"
);

const backendPhrase = resourcesToBackend((language, namespace, callback) => {
    phrase.requestTranslation(language)
        .then((remoteResources) => {
            callback(null, remoteResources);
        })
        .catch((error) => {
            callback(error, null);
        });
});

const backendFallback = resourcesToBackend(localResources)

i18n
  .use(ChainedBackend)
  .use(initReactI18next)
  .init({
    backend: {
        backends: [backendPhrase, backendFallback]
    },
    debug: true,
    lng: "en",
    fallbackLng: "en",
    interpolation: {
      escapeValue: false, // not needed for react as it escapes by default
    }
  });

Esempio di app

https://github.com/phrase/react_native_sdk_example

La libreria i18next-Frase-backend implementa un backend di esempio per i18next che recupera le traduzioni dalle versioni OTA.

Per creare una nuova versione, la piattaforma i18next deve essere impostata per la distribuzione ed essere parte di una versione.

Utilizzo

Per inizializzare phrase:

import i18n from "i18next";
import { I18nextPhraseBackend } from "@phrase/i18next-backend";

i18n
  .use(I18nextPhraseBackend)
  .init({
    fallbackLng: 'en',
    backend: {
      distribuzione: "ID_DISTRIBUZIONE",
      segreto: 'YOUR_ENVIRONMENT_SECRET',
      appVersion: '1.0.0',
    }
  });

Caching

La libreria memorizza nella cache le traduzioni e non controllerà la presenza di nuove traduzioni per 5 minuti. Il caching può essere configurato impostando l'opzione cacheExpirationTime nella configurazione del backend a fini di test.

i18n
  .use(I18nextPhraseBackend)
  .init({
    fallbackLng: 'en',
    backend: {
      distribuzione: "ID_DISTRIBUZIONE",
      segreto: 'YOUR_ENVIRONMENT_SECRET',
      appVersion: '1.0.0',
      cacheExpirationTime: 60 * 5, // tempo in secondi
    }
  });

Esempio di app

https://github.com/phrase/ota-web-demo

La libreria Phrase-OTA-i18n implementa un backend di esempio per la gemma I18n che recupera le traduzioni dalle versioni OTA. Con la libreria, l'applicazione verifica regolarmente la presenza di traduzioni aggiornate e le scarica in background.

La libreria è valida per qualsiasi applicazione Ruby che utilizzi la gemma i18n.

Per creare una nuova versione, la piattaforma Rails deve essere impostata per la distribuzione ed essere parte di una versione.

Installazione

Utilizzo

Per generare la configurazione:

bundle exec rails generate phrase_ota:install --distribution-id <DISTRIBUTION_ID> --secret-token <SECRET>

Debug

La gemma ha una configurazione di Debug che può essere abilitata nell'inizializzatore impostando:

config.debug = true