Over the Air (Strings)

Com o SDK, o aplicativo verifica regularmente traduções atualizadas e faz download deles no background.

Verifique regularmente as últimas lançamentos do SDK Android, especialmente considerando upgrades.

Se as traduções não estiverem sendo atualizadas:

Se a versão errada de uma tradução estiver sendo usada, certifique-se de que um lançamento com as traduções mais recentes, a versão atual do aplicativo está disponível e o versionName para o aplicativo definido e está usando o formato <major>.<minor>.<point>.

Requisitos

Incluir o SDK

Adicionar um novo repositório ao root build.gradle:

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

Adicionar a biblioteca como dependência:

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

Suporte para Jetpack

Para ativar o suporte do Jetpack Compose para traduções OTA, execute estas etapas:

Configuração

Inicialize o SDK na classe de aplicativo e adicione o ID de distribuição e o segredo do ambiente. As classes herdadas do Aplicativo devem substituir o attachBaseContext para habilitar traduções fora do contexto da atividade:

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));
  }  
}

Injectar o SDK em cada atividade, p.ex., criando uma atividade base da qual todas as outras atividades herdam:

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

As traduções podem ser usadas como normalmente nos layouts:

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

E dentro do código:

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

Algumas bibliotecas não aceitam o desenchimento automático do contexto e esperam uma classe específica. Neste caso, a envoltura de contexto nos componentes Jetpack Compose pode ser desativada com:

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

Configurações para níveis de registro:

Alterar idioma

Se não estiver usando o idioma do sistema, um idioma diferente poderá ser definido no método setLocaleCode. O código do idioma (local) precisa estar presente em um lançamento.

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

Versão de aplicativo personalizada

O SDK usa a versão do aplicativo como padrão para retornar um lançamento que corresponda às restrições de lançamento para a versão mínima e máxima. A versão do aplicativo deve usar a versão semântica, caso contrário, nenhuma atualização da tradução será gerada. Caso o aplicativo não use a versão semântica, é possível substituir manualmente a versão do aplicativo usado.

Exemplo:

Phrase.setAppVersion("3.2.4");

A versão precisa ser definida antes de chamar updateTranslations( ).

Confirmar tempo limite

O tempo limite padrão para downloads de tradução está definido para 10 segundos.

O padrão pode ser alterado com:

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

Atualizar retorno

Se o tratamento de atualizações de tradução bem-sucedidas for necessário, anexe um operador de retorno:

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

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

As atualizações da tradução também podem ser acionadas manualmente. As traduções recém-checadas são exibidas no próximo lançamento do aplicativo.

Para tornar as últimas traduções disponíveis imediatamente, use o método Phrase.applyPendingUpdates(). Isso pode ser combinado com ouvir atualizações de tradução:

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

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

A interface não exibe traduções automaticamente e deve ser recriada.

Configurar centro de dados US

O centro de dados Phrase US também é aceito. O centro de dados US pode ser configurado chamando:

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

Fallback

Caso não seja possível acessar o Phrase devido a uma conexão de rede ausente do cliente ou uma interrupção de serviço, o SDK usa as traduções pacotadas do arquivo de recurso. Recomenda-se atualizar regularmente as traduções pacotadas no aplicativo. O SDK também cache as traduções localmente no dispositivo. Se houver esse cache, ele será usado até a próxima atualização da tradução.

O SDK usa o lançamento mais recente para as traduções. Caso o versionName para o aplicativo seja definido, será usado o lançamento mais recente que satisfaça às restrições de versão.

Adicionar um novo idioma

Criando o novo idioma no Phrase e criando um novo lançamento. O SDK busca o idioma quando este é o idioma do dispositivo de um usuário. Recomenda-se adicionar regularmente um novo strings.xml para novos arquivos de idiomas ao lançar uma nova versão do aplicativo ou os usuários verão apenas as traduções de fallback determinadas pelo Android na primeira inicialização do aplicativo.

Revisão

O SDK é de texto original fechado e não pode ser visualizado ou modificado. Se for uma exigência da organização, podem ser fornecidas auditorias. Entre em contato para obter mais detalhes, se necessário.

Personalizar visualização do suporte

As exibições personalizadas podem ser traduzidas usando atributos estilizados. Como o TypedArray não permite substituir os recursos, pequenas alterações na exibição personalizada são necessárias:

Exemplo de aplicativo

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

Com o SDK, o aplicativo verifica regularmente traduções atualizadas e faz download deles no background.

Requisitos

Esta biblioteca depende da versão 0.18.0 da biblioteca intl do Flutter.Siga o seu guia para adicionar suporte de localizações ao aplicativo.

Instalação

Adicionar o Phrase ao pubspec.yaml:

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

flutter:
  generate: true
  ...

Como na biblioteca intl, a geração de código é usada para processar arquivos ARB. Execute este comando para atualizar:

flutter pub run phrase

Usando build_runner:

flutter pub run build_runner watch

Uso

Inicializar o Phrase no arquivo 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: 'Demonstração de flutador',
      //..
      localizationsDelegates: PhraseLocalizations.localizationsDelegates,
      supportedLocales: PhraseLocalizations.supportedLocales,
    );
  }
}

Acessar mensagens com:

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

Personalizar

Atualizar comportamento

As traduções do OTA são atualizadas sempre que o aplicativo é lançado. Para desabilitar este:

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

Para atualizar manualmente:

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

Versão de aplicativo personalizada

O SDK usa a versão do aplicativo como padrão para retornar um lançamento que corresponda às restrições de lançamento para a versão mínima e máxima. A versão do aplicativo deve usar a versão semântica, caso contrário, nenhuma atualização da tradução será gerada. Caso o aplicativo não use a versão semântica, a versão do aplicativo pode ser substituída manualmente: é possível substituir a versão do aplicativo manualmente:

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

Configurar centro de dados US

O centro de dados Phrase US também é aceito. O centro de dados US pode ser selecionado aprovando o parâmetro de hostname da API relevante na configuração SDK:

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

Exemplo de aplicativo

https://github.com/phrase/flutter_sdk_example

Com o SDK, o aplicativo verifica regularmente traduções atualizadas e faz download deles no background.

O Mac Catalyst também é aceito.

O SDK pode ser instalado manualmente ou por meio do gerente de pacotes do Swift, Carthage ou Cocoa Pods.

Se as traduções não estiverem sendo atualizadas:

Se a versão errada de uma tradução estiver sendo usada, certifique-se de que um lançamento com as traduções mais recentes e a versão atual do aplicativo está disponível.

Swift Package Manager

Adicione o URL do repositório público (https://github.com/phrase/ios-sdk/). O Xcode lida com o restante da instalação automaticamente.

Cartago

Adicione a seguinte linha ao seu Cartfile:

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

Execute a atualização do carthage e adicione o PhraseApp.framework ao seu projeto como descrito na documentação carthage.

Cocoa Pods

Adicione a seguinte linha ao seu Podfile:

pod 'PhraseSDK'

Execute a instalação do pod. Se você é novo(a) no CocoaPods, consulte sua documentação.

Instalação manual

Execute estas etapas:

Configuração

Recomenda-se a chamada de ambas as funções dentro do AppDelegate no método didFinishLaunchingWithOptions.

Objetivo-C

Integrar o SDK no aplicativo 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;
}

Desativar o balanço

Para desativar o swizzling, defina PhraseSDKMainBundleProxyDisabled para YES no arquivo Info.plist.

Quando o recurso swizzling está desativado, as traduções atualizadas não são mais exibidas. A tradução ainda será sincronizada se updateTranslation for chamado e poder ser acessada com o método Phrase.localizedString().

Manuseio de versões do aplicativo

Para determinar qual lançamento deve ser retornado, o SDK requer uma versão semântica do aplicativo para que as traduções sejam atualizadas.

O SDK tenta obter uma versão semântica da seguinte maneira:

Se CFBundleShortVersionString estiver ausente ou não puder ser criado com uma versão semântica em conjunto com CFBundleVersion, o SDK lançará a mensagem PhraseSetupError.appVersionNotSemantic.

Desabilitar tradução para várias tabelas

Para evitar que o OTA traduza tabelas no pacote principal do iOS além da tabela padrão Localizável, defina a seguinte opção:

Phrase.shared.configuration.ignoreOtherTables = true

Chamadas

Anexe um operador de retorno para processar as atualizações de tradução bem-sucedidas:

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

Modo de depuração

Se forem necessárias mais informações, ative o modo de depuração para obter logon adicional do PhraseSDK.framework na consola:

Phrase.shared.configuration.debugMode = true

Confirmar tempo limite para solicitações

Defina um tempo limite para as solicitações contra o Phrase ligando:

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

O tempo limite padrão é de 10 segundos e conexões que levam mais de 10 segundos serão fechadas.

Fornecer substituição de idioma manual

Se não usar o idioma do sistema como local, um local diferente poderá ser definido na chamada init. O código de local precisa estar presente em um lançamento do Phrase:

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

Fallback

Caso não possam ser obtidas novas traduções do Phrase por meio do SDK, os arquivos de tradução mais recentes da instalação recebidos são usados. Se o aplicativo nunca recebeu novos arquivos do Phrase, ele usa os arquivos de tradução compilados do aplicativo. Isso evita erros em caso de qualquer dificuldade técnica ou erros de rede. Recomenda-se manter os seus arquivos de tradução compilados no aplicativo atualizados a cada lançamento.

Revisão

O SDK é de texto original fechado e não pode ser visualizado ou modificado. Se for uma exigência da organização, podem ser fornecidas auditorias. Entre em contato para obter mais detalhes, se necessário.

Com o SDK, o aplicativo verifica regularmente traduções atualizadas e faz download deles no background.

A biblioteca para traduções OTA só funciona com a biblioteca react-i18next.

Para instalar o React Native SDK, siga estes passos:

Exemplo de arquivo 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
    }
  });

Exemplo de aplicativo

https://github.com/phrase/react_native_sdk_example

A biblioteca i18next-phrase-backend implanta um exemplo de backend para i18next que recupera as traduções de lançamentos OTA.

Para criar um novo lançamento, a plataforma i18next precisa ser definida para a distribuição e fazer parte de um lançamento.

Uso

Para inicializar o Phrase:

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

i18n
  .use(I18nextPhraseBackend)
  .init({
    fallbackLng: 'en',
    backend: {
      distribuição: 'DISTRIBUTION_ID',
      segredo: 'YOUR_ENVIRONMENT_SECRET',
      appVersion: '1.0.0', '1.0.0',
    }
  });

Caching

A biblioteca está cacheando traduções e não verificará novas traduções por 5 minutos. O cache pode ser configurado definindo a opção cacheExpirationTime na configuração do backend para fins de teste.

i18n
  .use(I18nextPhraseBackend)
  .init({
    fallbackLng: 'en',
    backend: {
      distribuição: 'DISTRIBUTION_ID',
      segredo: 'YOUR_ENVIRONMENT_SECRET',
      appVersion: '1.0.0', '1.0.0',
      cacheExpirationTime: 60 * 5, // tempo em segundos
    }
  });

Exemplo de aplicativo

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

A biblioteca phrase-ota-i18n implanta um exemplo de backend para a joia I18n que recupera as traduções de lançamentos OTA. Com a biblioteca, o aplicativo verifica regularmente traduções atualizadas e faz download deles no background.

A biblioteca é válida para qualquer aplicativo Ruby utilizando a joia i18n.

Para criar um novo lançamento, a plataforma Rails precisa ser definida para a distribuição e fazer parte de um lançamento.

Instalação

Uso

Para gerar a configuração:

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

Debugging

A jóia tem uma configuração de debug que pode ser ativada no inicializador definindo:

config.debug = true