Flutter本地化翻译管理插件weblate_sdk的使用

weblate_sdk 是一个非官方的 SDK，用于在Flutter项目中集成Weblate服务，实现基于Web的持续本地化。以下是关于如何在Flutter项目中配置和使用weblate_sdk的详细指南。

开始使用

1. 添加依赖

首先，在pubspec.yaml文件中添加weblate_sdk包和Flutter本地化支持：

dependencies:
  weblate_sdk: latest
  flutter_localizations:
    sdk: flutter

2. 初始化SDK

接下来，在main.dart文件中的main函数里初始化WebLateSdk：

await WebLateSdk.initialize(
  token: 'your token', // 替换为你的token
  host: 'your host', // 替换为你的Weblate主机地址，例如'https://weblate.company.link'
  projectName: 'name of project', // 替换为你的项目名称
  componentName: 'name of component', // 替换为你的组件名称
  defaultLanguage: 'en', // 设置默认语言
  disableCache: false, // 可选参数，默认情况下禁用缓存（debug模式）或启用缓存（release模式）
  cacheLive: const Duration(days: 1), // 可选参数，设置缓存存活时间，默认为2小时
  fallbackJson: 'assets/default.json', // 可选参数，设置回退翻译文件路径
);

3. Android设置

确保在build.gradle中将minSdkVersion设置为至少19：

defaultConfig {
    minSdkVersion 19
}

参数说明

• token: 你的项目Token，可以在Weblate项目API访问设置中创建，并至少设置Languages权限。
• host: Weblate主机URL，必须以https://开头。
• projectName: Weblate项目名称。
• componentName: 项目的组件名称。
• defaultLanguage: 如果当前语言找不到键值，则使用此默认语言。
• disableCache: 是否禁用缓存，默认在调试模式下禁用，在发布模式下启用。
• cacheLive: 缓存的有效期，默认为2小时。
• fallbackTranslations: 回退翻译文件，在SDK未正确初始化或用户无网络连接时使用。

4. 配置MaterialApp

在MaterialApp中添加对本地化的支持：

supportedLocales: WebLateSdk.supportedLocales,
localizationsDelegates: [
  GlobalMaterialLocalizations.delegate,
  GlobalWidgetsLocalizations.delegate,
  GlobalCupertinoLocalizations.delegate,
  WebLateSdk.delegate,
]

5. 使用本地化字符串

在代码中使用context.localizedValueOf('key')来获取已本地化的字符串。如果需要格式化，可以这样做：

context.localizedValueOf('key', format: ['John Doe']);

注意：对于需要替换的部分，应该用大括号括起来，例如'Welcome {username}!'。

示例代码

下面是一个完整的示例应用，展示了如何在Flutter应用中使用weblate_sdk进行本地化：

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:weblate_sdk/weblate_sdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await WebLateSdk.initialize(
    token: 'your token',
    host: 'your host',
    projectName: 'name of project',
    componentName: 'name of component',
    defaultLanguage: 'en',
    disableCache: false,
    cacheLive: const Duration(days: 1),
    fallbackJson: 'assets/default.json',
  );
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      supportedLocales: WebLateSdk.supportedLocales,
      localizationsDelegates: [
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
        WebLateSdk.delegate,
      ],
      home: WebLateSdk.isSDKInitialized
          ? const HomeScreen()
          : const InitializationErrorScreen(),
    );
  }
}

class HomeScreen extends StatelessWidget {
  const HomeScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(context.localizedValueOf('tab_home')),
      ),
      extendBodyBehindAppBar: true,
      body: Center(
        child: Text(
          context.localizedValueOf(
            'test_welcoming',
            format: ['John Doe'],
          ),
        ),
      ),
    );
  }
}

class InitializationErrorScreen extends StatelessWidget {
  const InitializationErrorScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Initialization Error'),
      ),
      body: const Padding(
        padding: EdgeInsets.all(8.0),
        child: Center(
          child: Text(
            'Running app first time?\nPlease check your internet connection and try again.',
            textAlign: TextAlign.center,
          ),
        ),
      ),
    );
  }
}

请根据实际情况调整上述代码中的占位符（如your token、your host等），并确保按照文档中的提示完成所有必要的配置。此外，请不要忘记为各个平台添加互联网权限。如果你有任何建议或发现了bug，可以通过GitHub Issues向开发者反馈。