Development/Tutorials/Localization/Language Change

    From KDE TechBase


    Dealing with Language Changes
    Tutorial Series   Localization
    Previous   Writing Applications With Localization in Mind
    What's Next   n/a
    Further Reading   n/a

    Adding an option to change the language

    It can be extremely useful for a user to be able to change the language of a specific application. It is fortunately extremely easy to add such functionality to your program.

    If you are using the KXmlGuiWindow class for your main window, then you will already have an associated programname.rc file for it.

    Simply modify this file to contain:

    <Menu name="help">
        <Action name="switch_application_language"/>
    </Menu>
    

    And that is it! You will now have a Switch Application Language option in the Help menu.

    However the user will need to restart the application for the changes to take effect.

    Dynamically changing the GUI

    One step better is to change the language on the fly, as soon as the user has selected a new language.

    This can seem a fairly daunting task, as a typical program can contain many hundreds of translatable strings that will need to be retranslated, but fortunately a lot of the work is already done for, and just needs to be connected together.

    When the language of an application is changed, a LanguageChanged QEvent is sent to every single widget. The idea is that in the top level window you will listen for this event, tell the GUI to retranslate, tell the toolbars to retranslate, and then let any custom widgets clean up themselves.

    So in your class that inherits from KXmlGuiWindow, add to the header file:

      class MyWindow {
        ...
       protected:
        void changeEvent( QEvent * event );
        void retranslateUi();
        KAction *mSomeAction;
        KAction *mQuitAction;
      }
    

    and to the source file:

    MyWindow::MyWindow() : KXmlGuiWindow( 0 )
    {
      //setup the GUI.  There should be no i18n calls here, but instead
      //these calls should be in the retranslateUi() function
      //Set up the actions in the GUI
      mSomeAction = actionCollection()->addAction("something");
      mSomeAction->setIcon(KIcon("some-action"));
      connect(mSomeAction, SIGNAL(triggered(bool)), mWorkSpace, SLOT(newWorkSheet() ));
    
      //KStandardActions need to be handled careful.
      mQuitAction = NULL
      
      retranslateUi();
      // Use the KXmlGuiWindow class to setup the GUI
      setupGUI(ToolBar | Keys | StatusBar | Create);
    }
    
    void MyWindow::changeEvent( QEvent * event )
    {
      if (event->type() == QEvent::LanguageChange) {
        // This will setup the menu, toolbars etc again, using the new language
        setupGUI(ToolBar | Keys | StatusBar | Create);
        retranslateUi();
      }
      KXmlGuiWindow::changeEvent(event);
    }
    
    void MyWindow::retranslateUi()
    {
      // Set the window title
      setPlainCaption( i18n( "My Window" ) );
      // For custom actions, just set the text again
      mMyAction->setText(i18n( "&Do Something..." ));
      if(mQuitAction) {
        //If we have already set this up before, create a new dummy action
        // and grab what info we need from it
        KAction *tmpQuitAction = KStandardAction::quit( NULL, NULL, NULL );
        mQuitAction->setText(tmpQuitAction->text());
        mQuitAction->setWhatsThis(tmpQuitAction->whatsThis());
        mQuitAction->setToolTip(tmpQuitAction->toolTip());
        delete tmpQuitAction;
      } else
        mQuitAction = KStandardAction::quit( this, SLOT( close() ), actionCollection() );
    }
    

    Although these is fairly complicated, that's about all that's needed. Just be careful whenever you add a new string somewhere that it can be translated.

    The way it is done in Qt is to follow this pattern of having a retranslateUi() function that is called from both the constructor and from a LanguageChange event.